About Bob Martin's Clean Code Book

(A picture without 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 ambiguous attitude towards the books of Robert Martin ... There are quite a lot of sound and interesting thoughts in them, but sometimes they are expressed so categorically that they can be perceived incorrectly as an immature programming 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 take anything new from these tips.





So it turns out that the ideal audience for these books is an advanced developer, strengthened enough to critically evaluate the advice of the “gurus”, but not so hardy that these tips do not sound from the category “Thank you, Cap!”.

')

Although, it must be admitted that if in the book “Principles, Patterns and Techniques for Agile Development” there were a lot of controversial tips from my point of view , then in the “Clean Code” much more reasonable and pragmatic tips are given.



But since the paranoia in the book is also enough, so I want to start with ambiguous moments, and only then go to the joys.

Controversial and doubtful moments

In the "Clean Code" there are several frankly dubious moments. First, there is quite a lot of code in it, which is very difficult to read on the pages of a book. Chapter 15 discusses the improvement of 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 advice

The first rule: functions must be compact. The second rule: functions should be even more compact . ... It follows from the above that the blocks in the commands if , else , while , etc. must consist of a single line, which usually contains a function call. This not only makes the enclosing function more compact, but also contributes to documenting the code, since you can assign a convenient meaningful name to the function called in the block.



Some chapters are frankly weak. I do not understand the purpose of chapter 13 on parallelism, which provides only general information about the problems of multithreading, and then Appendix A deals with the same topics, 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.



The side effects are lies. Your function promises to do one thing, but it does something else hidden from the user . Sometimes it makes unexpected changes to the variables of its class — say, assigns them the values ​​of the parameters passed to the function ...



Despite this advice, the author in many examples uses code with side effects and discourages using arguments with all his might, 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 create all the test scripts that verify the correctness of the code with all combinations of arguments.



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



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



Doubtful advice

The coding standard determines where instance variables are declared; how classes, methods and variables are named; how are braces, 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, not pleased. Sometimes he “pleased” so much that he had to climb into the original in order to understand what was being said:



QUOTE

When you have a complete set of tests, you can do the 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 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 entire chapter 12 (from which this quotation is taken) is completely ruined by the fact that the term “design” is translated in it as “architecture”, which makes many author's advice controversial.



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



Since the content of the book is relatively simple, the translators managed only to “spoil” the impression, but not to bungle it completely.

Practical advice

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



About naming

Do not use names that convey implementation information. Names must reflect the level of abstraction at which the class or function operates.



About the clarity of the code

It is easy to write code that is understandable to us, because at the time of its writing we deeply understand the problem to be solved. Other programmers who will be involved in the maintenance of this code will not have this understanding.



On the length and expressiveness of names

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



About the contents of the functions

All operators in a function must be at the same level of abstraction, which must be one level below the operation described by the function name.



The advice seems simple, but it is very valuable. The code should be read as good prose, and for this it is simply necessary that the function contain operators of the same level.



Unit tests as a library learning tool

Learning someone else's code is not an easy task. Integration of someone else's code is also difficult. The simultaneous solution of both problems creates dual complexities. And 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 calls such tests "training tests."



I follow 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 fun one piece of advice. Let's do this: what does the magic constant 5280 say to you? Nothing? Strange, according to the author, this is one of the values ​​that you can safely "hardcode"!



Some numbers are so easily recognized that they do not have to be hidden behind named constants — provided they are used in conjunction 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 out of any context.



The quality of the book can be indirectly evaluated 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 Techniques” there appeared critical articles like “Contracts, State and Unit Tests” , then as a result of “Clean Code” there appeared “Five Principles of Clean Tests” and “Best Metric for Determining the Quality of a Code” .



Advantages : a decent amount of decent advice



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



Rating : 4-