How to write proper comments ? — Code Craft

Hi dear reader, I’m Xavier Jouvenot and this is the fifth article about Code Craft, by Pete Goodliffe. If you want, you can look at the previous article about ‘Self Documentation’, and you can find book here.

The chapter we will treat today, is named ‘ A Passing Comment — How to write Code Comments ‘.

Back to the basics — What is a comment ?

COMMENTS ARE MADE TO BE UNDERSTANDABLE AND MAINTAINABLE FOR THE NEXT PROGRAMMER

This statement means that you should avoid writing too much comments, this is a nightmare to maintain, and most people won’t read them. To avoid that, write ‘Self Documenting Code’, and don’t comment code which is self-explanatory.

Of course, there are some tools that can use comments to analyse your code, but this is a little part of the comments that you will write in your code. Most of them are for all the programmers that are going to interact with it, after you have written it, even the future you 😉

What should I put (and not put) in a comment then ?

The wanted ones

Too many times, we see comments trying to explain how the code works when there is nothing more precise than the code to describe what the code does. If you encounter poorly written code, if possible don’t comment it, but rewrite it to make it self-explanatory.

“Don’t document bad code — rewrite it”, The Elements of Programming Style by Brian W. Kernighan and P. J. Plauger 🙂

The other thing you want in your comment is to explain unexpected behavior like workaround and tricks you have to use, for example, to avoid a bug in a library or in a compiler.

The unwanted ones

The second point is that you should not write code in a comment. It will deprecate quickly since nothing will compile or interpret it. Prefer removing this code and use code versioning if you want to go back to this code.

The third point is to avoid putting restriction, limits or how the code should be used in comments. Instead try to enforce the behavior using Defensive programming or enforce the limits of your variable by defining a proper type.

Finally, don’t write any jokes, or personal message in your comments. Personally, I never encountered any of this, but this is really bad for the credibility of the program and is counterproductive.

How to work with comments

Comment layout

Two other points mentioned by the author, are:

  • Comments should be indented along side the code, to make them more coupled with the code they comment
  • Avoid Ascii art which are long to maintain.

Comment as flag

The author gives three flags that you can use and which are often spotted by IDE, to make you interact more easily with them:

  • Comment starting with XXX to reference hard to understand code.
  • Comment starting with FIXME to reference a code with a bug in it.
  • Comment starting with TODOto reference some implementation not done yet.

The author also mention that you may prefer throwing an exception instead of using the flag TODO so that you won't forget to actually implement what is left to do.

Moreover, he also specify that you should avoid referencing bug fix in your code. Indeed, your code should state the present, what you have, instead of the past. To do that, you may prefer using a bug tracker 😉

Comment to write an algorithm

Conclusion

Comments can be a huge advantage when use correctly but can also mislead you or become a nightmare to maintain, so be careful when using them.

Thank you all for reading this article, And until my next article, have an splendid day 😉

Originally published at http://10xlearner.com on February 11, 2020.