In my previous post I showed an example of what not to do when writing comments. To my amazement this non-rant generated almost as many comments as this post.
After reading the comments and giving it some more thought I wanted to post a follow-up. I don’t believe these type comments are unique to a tool like VBCommenter, one development shop or one programming language. I believe this is a very common issue when documenting source code.
I had another post a couple years ago about documentation and my views haven’t really changed. I still believe the most important piece of documentation for a project is the requirements.
If you insist in commenting the code (which I’m not arguing against) I suggest the following rules:
Document WHY not WHAT
Even really crappy code can be debugged. Call me sick but I kind of like debugging crappy code from time-to-time because it is extra satisfying when I fix it. When you are cursing the previous developer’s name are you screaming at them, “WHAT are you doing”? or “WHY did you do that”? I find it a lot easier to figure out the what but the why can be a little trickier.
Remember you who are writing for
The primary person the in code documentation is for is the developer(s) that inherit your code not for you. I believe a class header outlining the purpose of the class is far more valuable than commenting every method. If you had to explain the application to a developer that was going to take over for you what would you tell them? Would you say, “here is the page_load event, it will load the page”? Probably not, you are hopefully going to tell them some of the challenges you ran into and why the application is the way it is.
Never Copy and Paste Comment Block headers
Please, if you must copy comment headers remember to update them. I don’t know how many times over the years I have read the comments of method A right above method B because the developer copied the comments and didn’t update them.
Read them and keep them current
If you are maintaining some code and the person before you took the time to write good comments make sure they are still current after your change. If you aren’t going to bother updating them it is better to delete them than leave comments that don’t match the code.
Commenting code can add value to a project but it is a team effort. I don’t believe there is any magic to writing good comments but it does take time and you do have to put some thought into it. If you hate writing comments that much you could always try this.
