A Short Summary on Clean Code
Last edited on: October 13, 2021 12:15 AM
This blog post summarizes the guidelines and best practices for writing high-quality code from the book Clean Code by Robert C. Martin. Download the PDF version of the book here.
Meaningful Names
Use Intention-Reveraling Names
The name of a variable, function, or class, should tell you why it exists, what it does, and how it is used. If a name requires a comment, then the name does not reveal its intent.
1 |
|
Implicity of the code: the degree to which the context is not explicit in the code itself.
Avoid Disinformation
We should avoid words whose entrenched meanings vary from our intended meaning.
1 |
|
Spelling similar concepts similarly is information. Using inconsistent spellings is disinformation.
Make Meaningful Distinctions
Number-series naming is noninformative.
1 |
|
Noise words are redundant and another meaningless distinction.
1 |
|
Use Pronounceable Names
Programming is a social activity. Make names pronounceable so that intelligent conversations are possible.
Use Searchable Names
Single-letter names and numeric constants are not easy to locate across a body of text. In this regard, longer names trump shorter names, and any searchable name trumps a constant in code.
1 |
|
The length of a name should correspond to the size of its scope.
Avoid Encodings
Encoding type or scope information into names simply adds an extra burden of deciphering.
1 |
|
Avoid Mental Mapping
Single-letter names for loop counters are traditional, but in most other context a single-letter name is a poor choice.
1 |
|
Professional programmers understand that clarity is king.
Class Names
Classes and objects should have noun or noun phrase names. A class name should not be a verb.
1 |
|
Method Names
Methods should have verb or verb phrase names. Accessors, mutators, and predicates should be named for their value and prefixed with get
, set
, and is
.
1 |
|
Avoid Ambiguity
Pick one word for one abstract concept and stick with it. A consistent lexicon is a great boon.
1 |
|
Avoid using the same word for two purposes with different semantics.
Solution and Problem Domain Names
Use the name from the solution domain such as computer science terms, algorithm names, patter names, math terms, and so forth.
1 |
|
Seperate solution and problem domain concepts.
Add Meaningful Context
Place names in context by enclosing them in well-named classes, functions, or namespaces.
1 |
|
Shorter names are generally better than longer ones, so long as they are clear. Add no more context to a name than is necessary.
Function
Keep Functions Small
The whole function must fit into the screen and not too wide so that it’s easy to read without scrolling. Every function should be around four lines long.
This implies that the blocks within if
, else
, while
statements should be a function call which also adds documentary value.
The indent level of a function should not be greater than one or two.
1 |
|
Do One Thing
Functions should do one thing. They should do it well. They should do it only.
The reason we write functions is to decompose a larger concept into a set of steps at the next level of abstraction.
A function is doing more than one thing if we can extract another function from it with a name that is not merely a restatement of its implementation.
One Level of Abstraction per Function
Mixing levels of abstraction within a function is always confusing.
1 |
|
The Stepdown Rule: Every function should be followed by those at the next level of abstraction so that we can read the program as though it were a set of paragraphs.
Avoid Switch Statements
Use polymorphism and bury the switch statement in the basement of an abstract factory.
Use Descriptive Names
A long descriptive name is better than a short enigmatic name.
1 |
|
Try serveral different names and read the code with each in place. Be consistent in your names.
Function Arguments
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.
Common Monadic Forms
There are three reasons to pass a single argument into a function.
1 |
|
Flag Arguments
Passing a boolean into a function is a terrible practice.
1 |
|
Dyadic Functions
A function with two arguments is harder to understand than a monadic function.
1 |
|
Triads
For triads, the issues of ordering, pausing, and ignoring are more than doubled.
Argument Objects
Arguments can be wrapped into a class of their own.
1 |
|
Argument Lists
Sometimes we want to pass a variable number of arguments into a function.
1 |
|
Verbs and Keywords
Function names can explain the intent of the function and the order and intent of the arguments.
1 |
|
Avoid Side Effects
Functions can make unexpected changes to variables of its own class, parameters passed into the function or system globals. This can result in strange temporal couplings and order dependencies.
Arguments are most naturally interpreted as inputs to a function. Anything that forces you to check the function signature is a cognitive break and should be avoided.
Command Query Seperation
Functions should either do something or answer something, but not both.
1 |
|
Prefer Exceptions to Returning Error Codes
Returning error codes from command functions violates command query seperation, leading to deeply nested structures.
1 |
|
It is better to extract the bodies of the try
and catch
blocks out into functions of their own. A function that handles errors should do nothing else.
Avoid Repetition
Duplication is a problem because it bloats the code, requires manifold modification for a change of algorithm and magnifies opportunity for an error of omission.
Structured Programming
Every function, and every block within a function, should have one entry and one exit.
There should only be one return
statement in a function, no break
or continue
statements in a loop, and never any goto
statements. It is only in larger functions that such rules provide significant benefit.
Comments
The proper use of comments is to compensate for our failure to express ourself in code. Programmers cannot realistically maintain comments.
Inaccurate comments are far worse than no comments at all.
Comments Do Not Make Up for Bad Code
Clear and expressive code with few comments is far superior to cluttered and complex code with lots of comments.
Explain Yourself in Code
There are times when code makes a poor vehicle for explanation. In many cases it’s simple to create a function that says the same thing as the comment you want to write.
1 |
|
Good Comments
Some comments are necessary or beneficial.
Legal Comments
Copyright and authorship statements are necessary and reasonable things to put into a comment at the start of each source file.
1 |
|
Informative Comments
It is sometimes useful to provide basic information with a comment.
1 |
|
Explanation of Intent
Sometimes a comment provides the intent behind a decision.
1 |
|
Clarification
Sometimes it is helpful to translate the meaning of some obscure argument or return value into something that’s readable.
1 |
|
There is a substantial risk that a clarifying comment is incorrect and it is diffcult to verify.
Warning of Consequences
Sometimes it is useful to warn other programmers about certain consequences.
1 |
|
TODO Comments
It is sometimes reasonable to leave “To do” notes in the form of TODO
comments.
1 |
|
TODO
s are jobs that the programmer thinks should be done, not an excuse to leave bad code in the system.
Amplification
A comment may be used to Amplify the importance of something that may otherwise seem inconsequential.
1 |
|
All articles in this blog are used except for special statements CC BY-SA 4.0 reprint policy. If reproduced, please indicate source Ziyi Zhu!