Smells and Heuristics - Part 1

The second edition of Robert C. Martin’s (Uncle Bob) bestseller “Clean Code” was released at the end of last year, and I am currently reading it. Uncle Bob also covers much of his old book in the new one, but a chapter from the old edition is now missing (as far as I can tell).

This is the occasion for me to write my first (real) blog entry about Chapter 17, “Smells and Heuristics”. Due to the number of subchapters, I will split this chapter into three blog entries. These blog entries should also serve as a reference for me. Nobody can always keep all details in mind.

I will try to describe every smell in my own words. But it may happen that some phrases are the same because Uncle Bob has already hit the nail on the head.

Comments

C1: Inappropriate Information

Comments should not store information that belongs in other systems, such as version control or issue tracking. Things like change logs, author names, last-modified dates, or ticket numbers only add clutter to source files. Comments should focus on technical insights about the code and design.

C2: Obsolete Comment

An obsolete comment is one that has become outdated, irrelevant, or wrong. Because comments age quickly, avoid writing comments that will soon lose accuracy. If you find one, update it or remove it immediately. Otherwise, it drifts away from the code it once explained and turns into misleading noise.

C3: Redundant Comment

I think this example is self-explanatory, and it is clear that this comment is unnecessary:

i++; // increment i

Javadocs or doc-comments that does not add additional information are also redundant and unnecessary:

/**
 * @param sellRequest
 * @return
 * @throws ManagedComponentException
 */
public SellResponse beginSellItem(SellRequest sellRequest)
  throws ManagedComponentException

Comments should say things that the code cannot say for itself. (try to name classes, functions and variables to tell the story)

C4: Poorly Written Comment

If a comment is necessary, take the time to write a good, clear and understandable information. Don’t ramble. Don’t state the obvious. Be brief.

C5: Commented-Out Code

Commented-out code is usually old, unclear, and left behind because no one wants to remove it. Over time, it becomes more and more outdated, clutters the codebase, and distracts anyone trying to understand the module.

If you find commented-out code, delete it. Version control still keeps the history, so it can always be restored later if it is truly needed.

Environment

E1: Build Requires More Than One Step

Building a project should be simple and straightforward. You should not need extra manual steps, obscure commands, or missing artifacts just to get it running. After checking out the code, one clear build command should be enough.

git clone https://github.com/some-repo
cd some-repo
npm ci

E2: Tests Require More Than One Step

Running all unit tests should be quick and easy. Ideally, it takes just one command or button click, so anyone can verify the code without hassle.

Functions

F1: Too Many Arguments

Functions should take as few arguments as possible. Zero is ideal, one or two is fine, but more than three should be avoided.

F2: Output Arguments

Aviod them, they are counterintuitive. Arguments are expected to be inputs, not outputs.

F3: Flag Arguments

Boolean (flag) arguments signal that a function is doing multiple things. They make code harder to understand and should be avoided.

F4: Dead Function

Delete methods that are never called. The version control will still remember. And do not comment-out 😉