Clean Code Cookbook

Chapter 8. Comments

The proper use of comments is to compensate for our failure to express ourself in code.

Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship

8.0 Introduction

Back in the days of assembly language programming, the distance between what you intended to say as a programmer and how the computer worked was huge. Every few lines (sometimes on every line), you needed a little story to help you understand what the next few instructions meant. Today, comments are often a failure to choose good names. You will only need them to describe very important design decisions. They are dead code since they don’t compile or run. Comments tend to diverge from the code they once described. They become floating islands of irrelevance and misdirection in the code. Clean code needs almost no comments at all. You can find some criteria on how to use them in the following recipes.

Assembly Language

Assembly language is a low-level programming language to write software programs for specific computer architectures. It is a human-readable language imperative code that is designed to be easily translated into machine language, which is the language that computers can understand.

8.1 Removing Commented Code

Problem

You have commented code.

Solution

Don’t leave commented code. Use any source version control system and then safely remove the commented code.

Discussion

Before the 2000s, version control systems were uncommon and automated tests were not an established ...