fredag 24 april 2015

A Comment on Comments

During recent years I have worked with many very tech savvy people worthy of a lot of respect for their insight in embedded development. However, the discussion regarding comments seems to never die. The more tech oriented the developers, the less they seem to like comments in source and the more they seem to believe self commenting code exist. It doesn't. What exist is self commenting thoughts in your head. I have no chance whatsoever to get a good grasp of your ideas without reading them, or asking you.

I have always taken a more customer focused approach, hoping that I won't have to explain myself too many times when I hand over the result of my efforts. Here are some things I would like to point out to all of you that doubt the usefulness code comments:

  • Code in itself can only describe what it does. Everything else are left out. All the experience you gained through experiments, fixing bugs and working with the environment is lost if you don't document it.
  • Code can't explain what it doesn't do. All the alternatives to the approach you have taken. All the quirkyness of the libraries you are using. That takes a long time to get your head around as a new employee or contractor.
  • Code doesn't explain its purpose. In best case, you can read out something from the function name or similar, but most of the time names like openAuxChannel leave you wandering WHY you would like to open an auxiliary channel.
There are lots of other reasons to write and maintain the comments in the source. But there is also the question of the cost for commenting code. If you comment your code you spend time that not feel very productive. In one sense that's correct, you don't write code, so you're not moving towards the goal of the project. But quality has to be considered too, and maintainability and tracability are such parameters. Without them, the quality of your code is poor. It eventually boils down to the cost of developing a feature vs. the cost of owning it. Over time, the cost of owning poor code is MUCH higher than the gain of developing poor code.

So, in the trade-off of commenting source and writing new features, I would like to promote some techniques that I practice:
  • Use doxygen! You might not like browse the source in rendered HTML or PDF documents, but it gives others a great overview and a starting point that lets them get get up to speed with the source quickly.
  • Write commenting scripts that puts skeletons of comments in your files, classes, members and functions. The cost of developing such a script is a lot less than the effort it saves. It takes away a lot of boring work as well! Often the IDE has some functionality for this, but I often get more fields into my doxygen comments with a script.
  • Don't comment getters and setters. Programmers are not stupid, they will understand anyway. Though, if you have a script putting doxygen comment on them, they will become browsable when the documentation is rendered, and that's very convenient.
  • Make sure you add comments to algorithmic code in the functions. These sections of comments are the most valuable. The not only explain your algorithm, it will affect your design too. If you notice that you have to explain flags and states set in objects or structures in other modules etc. it shows that your approach to the problem is probably not coherent enought, or easy enough. If you can't explain what you have done, you should refactor it.