Comments - Do you follow the general commenting rules?
25/01/2019 2:12 PM by
Partho P. Das
There is almost always a better alternative to adding comments to your code.
What are the downsides of comments? What are the alternatives? What are bad and good types of comments?
There is almost always a better alternative to adding comments to your code. [Chapter 4: Comments, Clean Code is a treatise par excellence on the topic.]
What are the downsides of comments?
- Comments don't participate in refactoring and therefore get out of date surprisingly quickly.
- Comments are dismissed by the compiler (except in weird languages like java) and therefore don't participate in the design.
- Unless strategically added, they place a burden on the reader of the code (they now have to understand 2 things: the code and your comments).
What are the alternatives to comments?
- Change name of the element (class, function, parameter, variable, test etc.) to a longer more apt name to further document it.
- For ‘cryptic’ code (perhaps to optimize it), rewrite it in simpler terms (leave optimization to the runtimes).
- Add targeted unit tests to document a piece of code.
- Innovative techniques that are well known solutions to common code smells e.g.:
- For large methods/classes, break them and have longer names for them.
- For a method with large number of parameters, wrap them all up in a Parameter Object.
- <pair up with someone else, think… be creative.>
What some *bad* types of comments?
- That explain the "what"/"how" of the code. Basically the code rewritten in your mother tongue.
- Documentation comments in non-public surface area.
- Commenting out the code itself (perhaps to work on it later? That’s what source control is for).
- TODO comments (Little ones are OK, don't leave them there for too long. The big effort TODOs - say that are over an hour or two - should have a work item URL to it).
- And many more…
What some *good* types of comments?
Very few of these really. Although even these are subject to all the downsides of comments.
Note that a lot of punch can be delivered in 140 characters! Twitter previously?
- Comments that explain the why (e.g. strategic insights).
- … that hyperlink to an external source where you got the idea/piece of code.
- … that hyperlink to a Bug/PBI for adding some context.
- … that are documentation comments for your next-biggest-thing-on-Nuget library.
- … that are real apologies (perhaps you had to add some gut-wrenching nasty code just to meeting time constraints, must be accompanied by a link to Bug/PBI).
Last but not the least, some parting words
himself:"A comment is an apology for not choosing a more clear name, or a more reasonable set of parameters, or for the failure to use explanatory variables and explanatory functions. Apologies for making the code unmaintainable, apologies for not using well-known algorithms, apologies for writing 'clever' code, apologies for not having a good version control system, apologies for not having finished the job of writing the code, or for leaving vulnerabilities or flaws in the code, apologies for hand-optimizing C code in ugly ways."
- Uncle Bob (Robert Martin of 'Clean Code' fame)
Do you feel this rule needs an update?