Mike’s Dump

April 15, 2005

Is there any documentation for that?

Filed under: Work — mikesdump @ 10:05 am

A long time ago I had a sign on my wall that said, “Developers don’t document. If it was hard to write it should be hard to
understand”. I had it there because I thought it was funny but at least part of me agreed with that statement. Not that the code should be hard to understand but if the code is written clear enough (descriptive variables and method names) then why should a programmer document the application. That mentality didn’t last that long once I started working in the real world. Everything might be crystal clear at the time of writing an application of but few months go by and you start to forget the details. I started to realize that some documentation outside of the code is very important to be able communicate to people that don’t need to be intimate with the code at the time.

I still believe that any decent developer is going to be able to look at well written code and be able to debug a problem but without an overview of the design. Without the overview though, it is possible to cause more problems by making a change in a system you don’t  understand unless you are extremely cautious. Ideally the system has unit tests that will protect the developer from making those types of changes but I would  guess in most cases that would be the exception instead of the rule.


The one piece of documentation that I believe is an absolute must and that must be kept up to date is the requirements document. More  specifically, what is the purpose of the functionality? What business problem is it trying to solve. Having this information gives a developer the ability to understand what the code should be doing and not just what it is doing. Of course, the developer that is writing the code should have requirements but I’m am talking about the developer that is required to fix something that nobody has touched in a few years and nobody is left that understands how it works or what it was supposed to do. All the code that makes up the application should answer the purpose
question but then you are trying to see the forest from the trees. So hold on to the requirements some developer is going to need them. I know I did today.

Advertisements

1 Comment »

  1. In my previous post I showed an example of what not to do when writing comments. To my amazement this…

    Comment by Mike's Dump — June 25, 2007 @ 9:25 pm | Reply


RSS feed for comments on this post. TrackBack URI

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Create a free website or blog at WordPress.com.

%d bloggers like this: