Introduction

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

Redundant comments break the DRY principle because they are a form of repetition

Intent

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.

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.

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.