Clean Code – Comments

coryWelcome 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, 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 3 – Clean Code Naming

Part 4 – Clean Code Conditionals

Part 5 – Clean Code Functions

Part 6 – Clean Code Classes

Part 7 – Clean Code Comments

Part 8 – Clean Code Summary

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.

Zombie Code

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.


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.

Bloated Header

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.

Defect Log

Avoid comments that only describe source control metadata because that’s exactly what source control is for.

Clean Comments

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.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s