Welcome to Part 7 of this review of the Pluralsight course Clean Code: Writing Code for Humans by Cory House.
Cory is a Microsoft MVP in C#, founder of OutlierDeveloper.com, avid tech reader, and speaker. He believes in clean code, pragmatic development, and responsive native UIs.
Here are the links to each part in this series:
Part 1 – Writing Code For Humans
Part 2 – Clean Code Principles
Part 4 – Clean Code Conditionals
In this episode, we look at some examples of good and bad comments.
Cory asks the question “Are comments great, or a code smell?” and gives the answer “Yes there are!”
Necessity and Crutch
Comments are both a necessity and a crutch, and here Cory gives general rules on when and when not to use comments.
Next we look at some types of comments to AVOID.
Redundant comments break the DRY principle because they are a form of repetition
These explain what the code intends to express. Much better if the code itself expresses this.
Apologies and Warnings
Cory describes this as malpractice and he is right. Instead of apologising, fix the issue.
Yay! Kill Your Zombie Code!
Cory discusses the common causes of zombie code: risk aversion, and hoarding mentality.
Next he explains how zombie code damages your signal to noise ratio, creates ambiguity, hinders debugging and refactoring, and adds noise to searches.
KILL YOUR ZOMBIE CODE
Dividers and Brace Trackers
Back in my old VB.NET days when text editors were very primitive and I before LINQ was invented, I used to use brace trackers (end if trackers?) nearly all the time.
Modern text editors and IDEs will now highlight matching opening and closing braces for you, and brace trackers should never be required these days. If you see them, remove them.
Another hideous “best practice” from an earlier era in programming. Ghastly! Thankfully source control is pretty ubiquitous today, and bloated headers are becoming a much rarer sight.
Avoid comments that only describe source control metadata because that’s exactly what source control is for.
I have seen TODO comments plenty of times before, but never seen HACK comments before.
I recommend avoiding TODO comments unless you have specific processes in place around them, e.g. we cannot go live with TODO comments in place. They are only useful if they are very temporary. As Cory says, you should standardize as a team.
In a previous job, there were around 250 TODO comments in the codebase from many years ago. Nobody could remember or tell which if any were still relevant, but nobody wanted to delete them either just in case they were important. I expect that most of them still live on in the codebase today.
Other examples of clean comments that Cory describes are summary comments and documentation that can’t be expressed in code.