// No comments

“Comments should account for 5% of the total points” my fellow teacher declared.

In the fall of 2019, I was co-teaching an introductory course in computer programming and got into a disagreement on whether the students should be required to incorporate comments into their project submission.

“I want the students to develop good practices early on in their career. Surely, you’ll agree that adding comments improves code quality?” the fellow teacher asked me, almost righteously, a little miffed at my pushback.

I disagreed, and emphatically. Being encouraged to sprinkle comments everywhere is probably the worst programming practice being taught in school. Barring certain cases where comments are justified (I cover that later), adding comments is an anti-pattern, and an excessively commented code-base suggests a need to refactor.

Wait, what is this heresy? Comments can’t possibly hurt. Can they?

Here are the two reasons why I consider comments to be an anti-pattern:

1. They invariably go out of date. People forget to update comments as code gets refactored and features are developed. When this happens, comments become the root cause of the very thing they are meant to avoid — confusion. This is especially true at large companies where there are several people actively changing a common codebase…