Comments - Do you follow the code commenting standards?
Last updated by Nick Curran [SSW] 3 months ago.See historyThere 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 are some bad comments?
- Those that explain the "what"/"how" of the code. Basically the code rewritten in your mother tongue
- Those that 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 are some good comments?
- 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 from @UncleBob 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)