As developers, it’s been drilled into our heads that we must provide documentation for our programs … both inside the code, as comments, and for end user’s use.
One thing I’ve noticed that we tend to neglect, however, is to document the DECISIONS we make. Why did we select one implementation over another.
Case in point:
Last week, a co-worker and I were looking at some code that was written a few weeks ago … the code was clearly wrong, and the correct implementation was obvious to both of us. The problem is: we both remembered discussing this particular implementation … and we know that the decision not to implement it in the ‘obvious’ way was rejected. Unfortunately, neither of us could remember WHY that implementation was rejected.
Obviously, if we had documented the various implementations we had considered … and why we rejected or selected them, it there would have been a lot less head scratching.
I could not agree with this more! Absolutely right. In my opinion, commenting the decisions needs to happen right at the point of implementation as opposed to some fat book of obsolete stuff that no one ever looks at because it’s never kept current.
I haven’t done it nearly consistent enough, but as a custom developer I have also added a comment to the code that so and so required it. It started way back when I had a feeling that I was changing a block (feature) for the n’th too many times, flip flopping between processes. Turned out that one “owner” user would require version A than a quarter or 6 months later another “owner” user would require version B. Then enough later that everyone forgot who/why the first “owner” user would require version A again. And around the wheel we would go. With the user comment I finally caught on and told the users to get together and get their issues settled.
It can also help settle who is the real owner and needs to be consulted on the first attempt to change something. Or who slipped something around the real owner. :,)
Those are the areas I try my hardest to document. But alas, I FAIL!
The “WHY” comments are the only comments I like. They’re not something that can be gathered from the lines of code. It’s comments like “*Now add the discount to the price” that annoy me. Well written code shows me that I’m adding the discount to the code, I don’t need a comment that tells me that too. All that can happen with comments that tell you “WHAT” the code is doing is that they fall out of sync w/the code.
Heh, my favorite comments are the ‘indicator summaries’ that are at the top of every program … included from a template and absolutely NEVER updated (not even when the program is initially written). Of course I don’t use indicators anymore anyways.