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

by Robert C. Martin

Writing clean code is what you must do in order to call yourself a professional. There is no reasonable excuse for doing anything less than your best.

“Honesty in small things is not a small thing.”

God is in the details, said the architect Ludwig mies van der Rohe.

There are two parts to learning craftsmanship: knowledge and work.

You must gain the knowledge of principles, patterns, practices, and heuristics that a craftsman knows, and you must also grind that knowledge into your fingers, eyes, and gut by working hard and practicing.

Be prepared to work hard while reading this book.

Remember that code is really the language in which we ultimately express the requirements.

We know good code matters because we’ve had to deal for so long with its lack.

It’s your job to defend the code with equal passion.

The only way to make the deadline—the only way to go fast—is to keep the code as clean as possible at all times.

So too being able to recognize clean code from dirty code does not mean that we know how to write clean code!

Indeed, isn’t continuous improvement an intrinsic part of professionalism?

The problem isn’t the simplicity of the code but the implicity of the code

So accountGroup or bunchOfAccounts or just plain accounts would be better.

This function reads much better when source and destination are used for the argument names.

Distinguish names in such a way that the reader knows what the differences offer.

A class name should not be a verb.

Methods should have verb or verb phrase names like postPayment, deletePage, or save. Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the javabean standard.4

Add no more context to a name than is necessary.

Functions are the first line of organization in any program.

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

Lines should not be 150 characters long. Functions should not be 100 lines long. Functions should hardly ever be 20 lines long.

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

Functions that do one thing cannot be reasonably divided into sections.

By their nature, switch statements always do N things.

“You know you are working on clean code when each routine turns out to be pretty much what you expected.”

The smaller and more focused a function is, the easier it is to choose a descriptive name.

A long descriptive name is better than a long descriptive comment.

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.

The parts we ignore are where the bugs will hide.

Reducing the number of arguments by creating objects out of them may seem like cheating, but it’s not. When groups of variables are passed together, the way x and y are in the example above, they are likely part of a concept that deserves a name of its own.

In the case of a monad, the function and argument should form a very nice verb/noun pair.

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.

So it is better to extract the bodies of the try and catch blocks out into functions of their own.

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

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

Replace the temptation to create noise with the determination to clean your code. You’ll find it makes you a better and happier programmer.

Source code control systems are very good at remembering who added what, when.

Don’t offer systemwide information in the context of a local comment.

It is a pity when a comment needs its own explanation.

Your style and discipline survives, even though your code does not.

Each blank line is a visual cue that identifies a new and separate concept.

If openness separates concepts, then vertical density implies close association.

So lines of code that are tightly related should appear vertically dense.

This is frustrating because you are trying to understand what the system does, but you are spending your time and mental energy on trying to locate and remember where the pieces are.

Variables should be declared as close to their usage as possible.

The common convention in Java, however, is to put them all at the top of the class.

If one function calls another, they should be vertically close, and the caller should be above the callee, if at all possible.