Tuesday, April 7, 2009

Road rules for commenting your code

I'll never forget the first programming professor I had in college. He was a developer for Coke in Atlanta, GA corporate offices and taught "Intro to Java" as a side gig. He was a good teacher so far as I can remember, very capable at presenting completely foreign material to a diverse group of students in a concise and understandable way, and for that I thank him. He made himself readily available for questions, including business hours when he was on duty at Coke if you had a pressing question that you needed to get in touch with him about.

However, one of the principals that he hammered us on was that you needed to comment all of your code. This included every class, every method...on down to every variable. Closing braces should have a comment on what block it was closing off whether it be an if-elseif block, or a for loop, or the closing brace on your class. Did not matter...it had better have a comment on it or you could count on 2 points coming off of your grade.

It was not until I graduated and entered the working world that I would discover that this was in fact, not the best practice to follow. I was surprised to find that the majority of developers on a large project I was involved with at work shunned the practice of comments (not always, but most of the time you could say). Why? They were quick to point out that comments quickly get outdated, and that it's better to rely on the code to tell you the story instead of the comment. The one caveat to this was that an interface (we were coding in java) should always have comments as it is a public and published contract.

I was reminded of this professor recently after having stumbled upon a series of articles by Robert C. Martin (otherwise known as Uncle Bob). These articles provide you with a glimpse into what you can expect to find in one of the most recent books he has been involved with, Clean Code: A Handbook of Agile Software Craftsmanship. They give a just shy of humorous but pragmatic viewpoint of how comments don't work sometimes... a lot of times. I've not had the chance to read the book yet, but if the article series of excerpts are a good representation of what is in the book, then I intend to be picking it up soon.

My personal viewpoint... definitely comment code that could be confusing. If this is the case though, then perhaps you should try to find a way to refactor the code to make more sense. I agree with my friend, comment interfaces that you write. Remove old commented out code as it is outdated and most likely will never be needed again. And if it is, that's what version control systems are for. And keep comments short and to the point... don't try to tell a story with your comment. If you are, then your code could probably use a refactoring in this instance as well.


  1. Their's a saying I remember from a friend - The comment is the code. If the code explains enough what it is doing, it hardly needs a comment. But in a project involving teams from different continents, comments help a lot.

  2. Very well said by your friend Rommel... hope you don't mind if I forward that one along ;).

    Take care,