Why do I document Code?

  • Posted by Scott on March 28, 2008
  • 3 comments

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  


Digg It!
DZone		StumbleUpon
StumbleUpon		Technorati
Technorati
Reddit		Del.icio.us
Del.icio.us		NewsVine
Newsvine		Furl
Furl		BlinkList
Blinklist



Related posts

Comments

Posted on March 29. 2008 11:07 PM

Dan R.

Dan R. us
Hmmm... disagree completely.

1) SRD is a great tool when the customer knows what they want. Unfortunately, they usually don't. Even when they say they do. And if you wait until they do to start building software, you better have a customer with a big budget because they'll be wasting money like crazy. The SRD is very outdated, I believe, in the new agile world. Moreover, using the SRD in the fashion you describe leads to stupid crap like "change controls" and a poor relationship between the customer and IT. "Oh, you wanted the background to be red? Well look here on page 2,944 it says "pink" so ... sorry, you'll have to take this change to the change control board next week and see if they can approve it before you turn 90 years old."

2) DMM ... can be done with documented database model, setup script, and design decision explanations where necessary. I don't need someone to document every single column other than to explain what it is -- and that really should be obvious in many cases by the name of the column -- if it isn't, then you may want to revisit your naming conventions. I certainly don't need a document describing that column SocialSecurityNumber is a required 9-character string... it's blatantly obvious from the DDL that the field is a CHAR(9) NOT NULL. Double documentation leads to desynchronization because nobody wants to update documentation that's already documented elsewhere.

3) SDD... IS your code. When you're all done, the design IS the code. You can't document that any better than in your code -- and if it's not in your code then you've done yourself and everyone else a huge disservice. Why would anyone go out of their way to create (or even read) a document that has exactly what the code has in it??? It's irresponsible to create documentation that isn't necessary.

4) Ok, I agree with a User Guide because such a guide must be written in the language of your users, not in code and certainly not by developers (unless they have a special skill for such documentation -- which, I can assure you, most do not). So specialized documentation -- frequently involving videos or walkthroughs or annotated screenshots -- must be created for the user base. HOWEVER... in many projects it is possible to INCLUDE your users in the development and thus sometimes you have a project where the USERS can write the documentation. Nobody writes a better user guide than an actual user.

I applaud you for believing that documentation is important. But I caution you that this does NOT require massive amounts of documentation. If I write my code in a self-documenting way, there is no reason to comment my code to tell you what it does. Unless I need to explain how it works in the overall scheme of things, in which case a few lines will do. But then I don't need to go out and write a separate document explaining all of this again.

Documentation is good if it has value, and is VERY VERY bad if it does not.

Dan

Posted on March 30. 2008 12:20 PM

pingback

codeverity.com
Pingback from codeverity.com

Documenting Code - Tim Weaver

Posted on April 1. 2008 12:19 PM

Scott

Scott us
I currently work at a company that is CMMI level 5 and these documents must be created for any software writing I do. The SRD has saved me multiple times in telling the customer no, not until we release v1. I for one wish, they would look at the SDD and only want the code and comments, but full document support is needed and therefore help documents must be created for it. ugh, what a pain.
I need a document writer more than most for my grammar is usually poor.

Add comment


(Will show your Gravatar icon)  

  Country flag

[b][/b] - [i][/i] - [u][/u]- [quote][/quote]