PreviousNext…

Documenting code

A good post about why we put up with poor code documentation, found via Erik. The post has some really good comments against it, and I would draw your attention to this one especially:

The act of *explicitly* writing out your thoughts forces a mental state that is quite different from when you just mull things over and then go code. Comments are as valuable to the person writing them as the people reading them.

I am nodding frantically at this; I've found it really helps to write your documentation first. I have a pretty standard "header" I put in my Lotusscript programs, covered in an article I wrote a while back, and it really helps me to fill out the "purpose" section before I write a line of code. Why? It keeps focus on what it is I'm trying to achieve. After all, one of the biggest issues with programs is not whether they do something, but whether they do the thing they were intended to do…

As someone else states in the comments, it also seems pretty pointless to painstakingly document what arguments each function, sub-routine or method requires. The code tells the programmer that already. An obvious point, but one lost on many people, including me (I don't do it any more, honest!)

To conclude, I find that there are just two things that are really helpful in documentation, beyond the usual author and change history details: (1) purpose — what does the damn thing do? — and (2) dependencies. If I change something, will I break something else (assuming I'm coding grubby little interfaces that I change at will)?

Comments

  1. I think I comment my code to much sometimes. I write comments as a type of aglorithm before I write the code this helps me see the structure of the code I am about to produce but makes the code look more complicated sometimes. I also think it would be cool if we have had something like JavaDoc for the automation of LotusScript documentation it would be useful for all sorts of reasons. I noticed the other day this example in the LDD Sandbox which is part of the way there.

    HTML Linked LotusScript Libraries linkjohn marshall#
  2. I definitely overcomment my code, but I do it for two reasons… One, I comment intent so that if something breaks, the person behind me might be able to figure out if the code was SUPPOSED to do that or if it was a bug I overlooked. And two, verbose comments help those just getting started follow what you do. Much of the code I write for a client is going to be maintained by a beginning developer. The comments help him to follow along and learn from the code…Thomas Duff#
  3. Tom, as I point out in my article, I definitely over-comment when it comes to doing code for junior developers, and I think that's the right thing to do.

    I learned Lotusscript by nabbing other people's programs and going through them. Well-placed commentary in that scenario would have definitely been beneficial!

    Ben Poole#

Comments on this post are now closed.

About

I’m a software architect / developer / general IT wrangler specialising in web, mobile web and middleware using things like node.js, Java, C#, PHP, HTML5 and more.

Best described as a simpleton, but kindly. You can read more here.

";