On Code Documentation

There are two major problems that I see when I look at my student’s documentation for their code.

  1. no documentation … we are talking about not even having a header with their name on it here for assignments
  2. too much documentation – repeat all code in comments!

Both of these are problems.  One may not seem like a problem but it in fact is.

The lack of documentation in its entirety is just a job of incompleteness.  Most students understand that when they don’t do it, they will lose marks.  They know they should but for whatever reason they didn’t.   Its like knowing you should exercise but you don’t…This post isn’t about that.  The complete lack of documentation is relatively simple to address.

This post is addressed to those that document everything.  I know students who do this are very proud of their work and they put a lot of effort in it.  I get that.  I’m not knocking that.  However, I would like to ask you to please please please please please stop doing it.  Don’t do it.  It isn’t better.  A bad comment is worse than no comments at all.

Here are a few commenting guidelines:

  1. please don’t repeat your code in your comments… your code is there… anyone reading it sees what it does if they need to know it.  “this is a for loop” is not useful.  “this loop runs 10 times” completely silly.  “assign 5 to x”….please stop. please stop.
  2. I have found that comments become sacred over time.  programmers do not hesitate to alter code… and yet comments…well you can’t touch those (sarcasm).  So, with this in mind, I encourage you to write as little comments in the body of your code as possible!  Your code should be clear enough to read.  Unless you are doing something very very tricky, don’t put in a comment in the body of the code.
  3. Comments that are useful explain reasoning, that may not be immediately obviously.  In my first programming job I was trying to hunt down a bug in a program and I saw this comment “find first sunday in april and last sunday in october”… I could tell thats what the code was doing… that wasn’t hard.  I then spent a day trying to figure out why they needed to do this and whether or not it was the cause of the bug.  What they did and how they did it was clear… the code said as much.  I couldn’t figure out why it was that this was something that needed doing.  Finally, I realized the why and changed the comment to “adjust time calculations for daylight savings times”… to me this makes way more sense.  I’m not saying how to do it (and the how has changed since then as the time of year that daylight savings time comes into effect has changed).

Here is are the three things you should document:

  1. Have a header!  State who wrote the code, major modification dates, versions etc
  2. state the intention of each function (not how but what it is suppose to do), its parameters, expected return value and restrictions.
  3. document unclear variables, units  of measurement etc.

That’s it.  Let the code speak for itself.

Advertisements

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