Clean Code: A Handbook of Agile Software Craftsmanship (Robert C. Martin Series)

by Robert C. Martin

Remember that code is really the language in which we ultimately express the requirements. We may create languages that are closer to the requirements. We may create tools that help us parse and assemble those requirements into formal structures. But we will never eliminate necessary precision—so there will always be code.

When others change bad code, they tend to make it worse.

Bjarne closes with the assertion that clean code does one thing well. It

Bad code tries to do too much, it has muddled intent and ambiguity

If a name requires a comment, then the name does not reveal its intent.

My personal preference is that single-letter names can ONLY be used as local variables inside short methods. The length of a name should correspond to the size of its scope [N5].

Java programmers don’t need type encoding. Objects are strongly typed, and editing environments have

One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king. Professionals use their powers for good and write code that others can understand.

The hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background. This is a teaching issue rather than a technical, business, or management issue.

The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that. This

FUNCTIONS SHOULD DO ONE THING. THEY SHOULD DO IT WELL. THEY SHOULD DO IT ONLY.

In order to make sure our functions are doing “one thing,” we need to make sure that the statements within our function are all at the same level of abstraction.

Mixing levels of abstraction within a function is always confusing.

Single Responsibility Principle7

Open Closed Principle8

The ideal number of arguments for a function is zero (niladic). Next comes one (monadic), followed closely by two (dyadic). Three arguments (triadic) should be avoided where possible. More than three (polyadic) requires very special justification—and then shouldn’t be used anyway.

Output arguments are harder to understand than input arguments.

we are used to the idea of information going in to the function through arguments and out through the return value. We don’t usually expect information to be going out through the arguments.

Using an output argument instead of a return value for a transformation is confusing. If a function is going to transform its input argument, the transformation should appear as the return value.

Flag arguments are ugly. Passing a boolean into a function is a truly terrible practice. It immediately complicates the signature of the method, loudly proclaiming that this function does more than one thing. It does one thing if the flag is true and another if the flag is false!

Side effects are lies. Your function promises to do one thing, but it also does other hidden things.

Anything that forces you to check the function signature is equivalent to a double-take. It’s a cognitive break and should be avoided.

In general output arguments should be avoided. If your function must change the state of something, have it change the state of its owning object.

Functions should either do something or answer something, but not both. Either your function should change the state of an object, or it should return some information about that object. Doing both often leads to confusion.

The real solution is to separate the command from the query so that the ambiguity cannot occur.

Prefer Exceptions to Returning Error Codes

Open Closed Principle (OCP) [PPP02].

Don’t Repeat Yourself13 13. The DRY principle. [PRAG

Duplication may be the root of all evil in software.

In the end, I wind up with functions that follow the rules I’ve laid down in this chapter. I don’t write them that way to start. I don’t think anyone could.

The art of programming is, and has always been, the art of language design.

“Don’t comment bad code—rewrite it.”

Nothing can be quite so damaging as an old crufty comment that propagates lies and misinformation.

Why am I so down on comments? Because they lie. Not always, and not intentionally, but too often. The older a comment is, and the farther away it is from the code it describes, the more likely it is to be just plain wrong. The reason is simple. Programmers can’t realistically maintain them.

It is possible to make the point that programmers should be disciplined enough to keep the comments in a high state of repair, relevance, and accuracy. I agree, they should. But I would rather that energy go toward making the code so clear and expressive

Inaccurate comments are far worse than no comments at all.

Truth can only be found in one place: the code.

however, that the only truly good comment is the comment you found a way not to write.

Any comment that forces you to look in another module for the meaning of that comment has failed to communicate to you and is not worth the bits it consumes.

What does that mean to us? It appears to be possible to build significant systems (FitNesse is close to 50,000 lines) out of files that are typically 200 lines long, with an upper limit of 500. Although this should not be a hard and fast rule, it should be considered very desirable.