The Sex and Cash Theory for Programmers

Why do I document Code?

28. March 2008 00:23 by Scott in   //  Tags: , , , , ,   //   Comments (59)

batflw

Hello and welcome to another session of why do I document code.  Today's contestants are:

1. The Software Requirements Document otherwise known as the SRD - This valuable little document tells the developer what to develop.  Is was started by the Carnegie Mellon.  It is used as a contract document between the developers and the customer.  The customer starts the document by what they expect the program to do.  Everyone knows that the customer always changes their mind, well if you use the SRD, they are held by a legally binding contract that specifically states what to develop.  You as a developer don't develop anything else except for what this document states.  Therefore if the customer changes their minds, well you can either point back to the SRD or decide to charge them more money.

2. The Database Maintenance Manual otherwise known as the DMM - This handy dandy contestant describes every little feature about your applications database.  IT describes the tables, the columns, the attributes of the columns, the generated script of the entire database, the user logins, the ways too install and upgrade the database on another machine, the DTS and last but not lease etc...  This basic manual describes in detail every single part of the database.  The reason for this is if you had a total hardware melt down and nothing works, well you now have a copy of the database that can be recreated using the script that was generated and put inside the file.

3. The Software Design Document also known as the SDD - This massive document describes all the methods, namespaces and functionality of the Code.  IT also describes the developers thoughts and opinions to why they code the application one way compared to another.  When I say everything, I mean everything. This document has all the developers thoughts and opinions when they were designing and developing the code.  Thank god most comments can be extracted via an XML parser.  The XML parsed comments can even put it into a nice little help file just like MSDN.com.  Where can you learn how to write one, well let me tell you.  Our good friends(Not really at all) at Bit Formation has made a great tutorial on how to write one.

4. The User Guide -  The user guide plain and simple is the thing users use to get around the application.  Every little thing that was EVER created by man has some sort of user guide attached to it.  These are a no-brainer, but long and tedious to write just like the other documents listed here today!

Now that you know our contestants, lets find out why you would do such a thing.

Alright, enough with the game show. I thought it would be a good starter.  I completely agree that all the documents though rather tedious and considered a time waster by developers is a necessary part of life.  Developers need to both COMMMENT CODE and write documentation.  That is the way it should be and should end up.  Documents are there in case you as the developer get into some kind of horrific accident and are no longer able to continue on.  They must find someone else to keep going.  Sorry, but that's the way life is.  You are writing the documentation incase you have to be replaced.  I currently work on a 20 year application and I know for a fact that I will not be working on this same application for another 20 years.  I just won't do it.  It is too boring and mundane.  I do know that some day, they will hire another guy or girl who will have to continue my work and when that day comes, the documents are there.

Ladies and gents, just think of documents as another day in the life of a developer. Things must be documented.

Scott P.

kick it on DotNetKicks.com