About Bob Martin's Clean Code Book

(The picture is not a hint, I just really wanted to add a cat to the article! After all, this is the main guarantee of popularity on the Internet, right? :))

I have a very mixed attitude to the books of Robert Martin ... They have a lot of sensible and interesting thoughts, but sometimes they are expressed so categorically that they can be perceived incorrectly by the fragile programmer brain. If the reader’s brain is strong enough to take the advice pragmatically, then there is every chance that he (the brain or the programmer) will not endure anything new.


So it turns out that the ideal audience for these books is an advanced developer who is strong enough to critically evaluate the advice of the "guru", but not so old that these tips do not sound like "Thank you, Cap!"

Although, I must admit that if in the book "Principles, Patterns and Techniques of Flexible Development" there were a lot of controversial tips from my point of view , then in the "Clean Code" there are much more reasonable and pragmatic tips. But since the paranoia in the book is also enough, so I want to start with the ambiguous moments, and only then go on to the joys.

Controversial and doubtful moments

There are several frankly dubious points in Clean Code. Firstly, it contains a lot of code, which is very difficult to read on the pages of a book. Chapter 15 discusses improving the command-line parser on 60 pages, 40 of which are solid Java code. Chapters 16-17 are written in the same format, but they are shorter, so it’s easier to follow the author’s reasoning.

Doubtful Tip
The first rule: functions should be compact. The second rule: functions should be even more compact . ... From the above it follows that the blocks in the if , else , while commandsetc. must consist of one line, which usually contains a function call. This not only makes the enclosing function more compact, but also helps to document the code, since the function called in the block can be assigned a convenient meaningful name.

Some chapters are frankly weak. I don’t understand the purpose of chapter 13 on concurrency, which gives only general information about the problems of multithreading, and then in Appendix A the same topics are analyzed, but in more detail and with the necessary examples.

But most of all, I am confused by the ambiguous attitude of the author to the state and side effects.

Side effects are a lie. Your function promises to do one thing, but does something else, hidden from the user. Sometimes it makes unexpected changes to the variables of its class - for example, assigns them the values ​​of the parameters passed to the function ...

Despite this advice, the author uses code with side effects in many examples and discourages using arguments by using the state of the object instead:

private String render(boolean isSuite) /*throws Exception*/
{
    this.isSuite = isSuite; 
    if (isTestPage())
        includeSetupAndTeardownPages(); 
    return pageData.getHtml();
} 
private void includeSetupAndTeardownPages() throws Exception {
    includeSetupPages();
    includePageContent();
    includeTeardownPages();
    updatePageContent();
}
private void includeSetupPages() /*throws Exception*/
{
    if (isSuite)
        includeSuiteSetupPage(); 
    includeSetupPage();
}

Doubtful advice
... Arguments create a lot of problems in terms of testing. Just imagine how difficult it is to compile all test scripts that verify that the code works correctly with all combinations of arguments.

What is the difference in terms of testing between a static method with four arguments and an instance method of an object with four fields? The number of boundary conditions is the same in both cases; just in the first case, we are dragging all the input data explicitly, and in the second case, implicitly through this .

The coding style in the book is given a lot of attention, while most of the tips are quite reasonable. But there are also very ambiguous:

Doubtful Council
The coding standard defines where instance variables are declared; what classes, methods, and variables are called; how braces are arranged, etc. A document with an explicit description of these rules is not needed - the code itself serves as an example of design .

Transfer

Translation, to put it mildly, did not please. Sometimes he “pleased” so much that he had to go into the original to understand what was at stake:

QUOTATION
When you have a complete set of tests, you can start cleaning code and classes.
To do this, the code is subjected to sequential processing (refactoring). We add a few lines of code, pause and analyze the new architecture.

WTF! How can adding two lines affect the architecture?!?! There are two options: either we are dealing with very long lines, or the authors here are not talking about architecture, but about something else, for example, about design! The whole chapter 12 (from which this quotation is taken) is completely corrupted by the fact that the term “design” is translated as “architecture” in it, which makes many of the author’s advice controversial.

As usual, the translators did not bother to leave the original terms, so I had to guess what is meant by the terms “logical binding” or “multithreading” (it turns out that these are high coupling and concurrency, respectively).

Since the contents of the book are relatively simple, the translators were only able to “spoil” the impression, but not completely screw it up.

Good advice

In fact, everything is not so bad and the "uncle" Bob companions give a lot of good advice. Here are some of them:

About naming
Do not use names that convey implementation information. Names should reflect the level of abstraction at which the class or function works.

About the comprehensibility of the code
It is easy to write code that is understandable for ourselves, because at the time of writing we deeply understand the problem being solved. Other programmers who will maintain this code will not have this understanding.

About the length and expressiveness of names
The length of the name should be related to the length of its scope. Variables with a tiny scope can be given very short names, but variables with a larger scope must have long names. ... Thus, the longer the scope, the longer and more accurate its name should be.

About the contents of functions
All operators in a function must be at the same level of abstraction, which should be one level lower than the operation described by the name of the function.

The advice seems simple, but it is very valuable. The code should be read like good prose, but for this it is simply necessary that the function contains statements of the same level.

Unit Tests as a Tool for Studying Libraries
Learning someone else’s code is not an easy task. Integrating someone else’s code is also complicated. The simultaneous solution of both problems creates dual difficulties. But what if you go the other way? Instead of experimenting and trying out a new library in the product code, you can write tests. Testing our understanding of third-party code. Jim Newkirk ( Jim Newkirk ) calls such tests 'educational tests'.

I have been following this advice for a long time and use unit tests to learn new tools and libraries. This allows you to better understand the library and easily return to examples of use, since they are always at hand.

Very amused one piece of advice. Let's just: what does the magic constant 5280 tell you? Nothing? Strange, according to the author, this is one of the meanings that can be easily "hard-coded"!

Some numbers are so easily recognizable that they do not have to be hidden behind named constants - provided that they are used in combination with clear code. ... The number 5280 - the number of feet per mile - is so well known and unique that the reader will immediately recognize it, even if it is located outside of any context.

The quality of the book can be indirectly estimated by the number of interesting quotes and the number of blog posts that appeared during the reading process. And if in the process of reading “Principles, Patterns and Methods” critical articles such as “Contracts, Status and Unit Tests” appeared, then as a result of the Clean Code, the Five Principles of Clean Tests and the Best Metric for Determining the Quality of the Code appeared .

Pluses : a decent amount of decent tips

Minuses : some of the tips are very controversial; sometimes advice is inconsistent; the translation is lame on both legs.

Rating : 4-