I'll Be Backend
Search lessons / @illbebackend
Code smells

Replace Comments with Code: Self-Documenting Code

Replace comments with code turns a comment that says what a line does into a name: a renamed variable, a constant or an extracted method. A what-comment is a second copy of the code that nothing keeps in sync, so it drifts into a lie when the rule changes. These lessons rename and extract until only the comments that say why are left.

Pick your language

Clean code: replace comments with code in Java, step 2: The comment still says 14Java · ~5 minReplace Comments with Code in JavaClean code: replace comments with code in C++, step 2: The comment still says 14C++ · ~5 minReplace Comments with Code in C++Clean code: replace comments with code in Python, step 2: The comment still says 14Python · ~5 minReplace Comments with Code in PythonClean code: replace comments with code in PHP, step 2: The comment still says 14PHP · ~6 minReplace Comments with Code in PHP

When to use it

Use it when

A comment tells you what the next line or block does.

Skip it when

The comment explains why, like a contract, a bug workaround or a law, or it documents a public API.

Spot it by

A comment above a short block, a one-letter variable, or a bare number in a condition.