Rules for Commenting




Font is Lavos Handy

Have you ever noticed that almost every popular code highlighting scheme places comments in low-contrast grey-blue-on-white or dark-blue-on-black? Commenting has long been considered an important part of programming, yet in practice comments are written to be ignored. I think it is because they are typically added to satisfy bureaucratic requirements rather than to supplement the source code with information.

I used to be a huge supporter of comments. I loved to see glorious, rich, voluminous comments in all the code I read. I loved to write them. I thought that for a program to be 60% comments was a pretty good start. But as my teams began to write cleaner code, they sometimes would brag that the code was so clean that it almost didn't need comments. Now I want all of my code to go beyond almost.

I also have come to value vertical space in a file. I want it to be filled with working code instead of boilerplate and fluff. I hate scrolling through noise to find the code.

A few simple points to consider, and we can all have code that is more clear and gloriously free from noise and distraction.

  • Comments provide information that is not expressible in code. Comments are meta-commentary. Anything that we can express in the code, we are duty-bound to express as code. Comments must never repeat the code, or the version control system. They are never substitutes for expressive code. Comments may express things like copyright, sources of algorithms, and reasons one algorithm or data structure is chosen over a more obvious alternative.
  • Comments are to be deleted when they are obviated. Any comment that provides information available in the code must be deleted. We don't need comments to tell us that x++ increments X. Any comment that does not provide value is to be deleted immediately. This applies to passages of code that are commented out. If the system runs fine without them, we don't need those lines.
  • We should always strive to obviate comments. When we see a comment, we should take it as a challenge. If we can make the code express the content of the comment through refactorings (renames, extracting variables/methods/classes, inlining methods/variables, etc) then we should do so post-haste. If we can do it, then the code itself becomes smaller and simpler. And then the obviated comments can be deleted.
Inevitably someone will read this card as giving them license to stop writing comments, but that is a gross misunderstanding. If one takes a big steaming mound of poor code and removes the comments, it becomes an even more unmaintainable steaming pile of crummy code. There is a system and a balance that needs to be understood here.

This card doesn't tell us not to write comments, but rather to avoid writing code that needs them. Do I write comments? Yes, when I absolutely have to. But now I know when I have to.

4 comments:

  1. In a couple cases I was faced with code that had a massive excess of horrid, stupid comments. In Eclipsed, I changed the syntax coloring so that comments were not grey but instead that they were white. Very effective! :-)

    ReplyDelete
  2. I'd put this a bit different:

    If you are reading the code of someone else then the code should be as clean und understandable that there is no need of comments despite the things you state under "Comments provide information that is not expressible in code"

    However, if you are using someone elses code and seeing therefore only the interfaces then it is very important to have comments that explain how the code will react to calls. I'm a .net guy and it is very helpful to have comments on the methods that state whether 'null' is a value that will be accepted in IntelliSense.

    For short: don't comment to explain the code, comment to make it easier usable.

    ReplyDelete
  3. That's no disagreement at all, Urs Enzler. If the .NET code could express whether null was acceptable or not, you wouldn't need that comment. Likewise if there were clear indications in code that null would NOT be returned. Of course, tests are specification, and specification is documentation, so you might have an out if you can find the tests.

    ReplyDelete
  4. Yes you're right. I had to give "provide information that is not expressible in code" some time to sink in.

    That's actually exactly my point.

    Thanks for clearing things up.

    ReplyDelete