“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.”
— Martin Fowler
When I was a computer science major in college, I had professors who used to dock points if my code wasn’t documented. It didn’t matter how well-written my code was, and it didn’t matter how well my code worked. If I didn’t include comments to describe my code, what my variables were, why I used certain functions and coding techniques, a project that could’ve gotten an A grade instead got a B.
That memory came back to me this evening at our SQL user group meeting this evening. Our guest speaker was Jen McCown, who gave a presentation called “T-SQL’s Hidden Support Feature.” (A description of her sessions can be found here, and I found a SQL Saturday link to it here.) Her presentation talked about a feature included with T-SQL (and just about every language imaginable). It is guaranteed to improve how people handle, develop, and maintain code, and it costs nearly nothing to implement.
What is this miracle feature, you ask?
Simply commenting code can save developers lots of headaches and development time. It can provide an explanation of how and why code snippets were used. It can describe variables, what they’re for, and how they’re utilized. It can describe program structures that help in debugging and maintenance. I even remember a comment to a SSC forum post by Jeff Moden who mentioned the return on investment of commenting code. It also reminded me of Steve Jones’ article about how important it is to comment code. I believe Jen’s presentation should be required for anyone who writes code. The benefits for commenting code are endless.
Commenting code is probably one of the simplest and most useful, yet most underutilized, methods of documentation. I’ve mentioned time and again about how documentation gets no respect in technology, and yet too many developers still refuse to do it. Jen’s presentation was a reminder of how important it is to document code; in fact, she also mentioned some points that didn’t occur to me. For example, documents such as Word, Wikis, or Confluence can get lost, misplaced, or buried. Code comments, however, stay with the code; it cannot get lost or separated from the code. (There were several other points she mentioned as well, but it’s her presentation, not mine, so I don’t want to take away from it.)
When I was in school, I was docked points when I didn’t comment my code. Sometimes, I think developers should be docked pay if they don’t do so. Commenting code is the simplest, yet most effective tools around. So you want to be a better developer? Then comment your damn code!