Nerdyworm is a tumblelog.

Code Comments

Continuing with the Clean Code Handbook, comments was the next chapter. Personally I don’t tend to comment much, it only obscures the code and the worst part of it as soon as I have to change the code I have to change the comment. Pretty much worthless. The only time where comments have real meaning is when the code so poorly named that the english version clarifies it.

To summarize the book:

1. Explain your self in code
2. Good Comments clarify, warn, and inform
3. Bad Comments clutter code, mislead, and add noise

The books a fine explanation of the various types of comments. I’ll personally keep to my standards of commenting and try to keep writing better code to avoid them. The best quote from this chapter was:

Don’t use a comment when you can use a Function or a Variable.

Bad:
// does the module from the global list  depend on the 
// subsystem we are part of? 
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) 

Good:
ArrayList moduleDependees = smodule.getDependSubsystems(); 
String ourSubSystem = subSysMod.getSubSystem(); 
if (moduleDependees.contains(ourSubSystem))