Code that is nice to read

Good code

There are many requirements for a good code: it must be optimal, it must have unit tests, it must be easy to reuse, it must comply with the company's code-standard and the spirit of the language. It should also be a pleasure to read.
I would like to talk about the rules that help me make the code readable.

Basic rule

I believe that readable code is one you can’t read about.
That is, a couple of three lines should be enough to say what a class or method does. Another couple of three - to roughly say how he does it.

Other comments

I noticed that there are some more fairly general rules that make the code nicer.

1. Comment in the header of the file   “What does this crap do?” - this is perhaps the most common question that I ask the author of the code. A comment helps outlines what will happen next. This is either a description of the class, or the principle by which functions are grouped.

2. Files no longer than 200-300 lines   . Huge files have the same problem as some Swiss knives: it is impossible to remember what this crap does.
It becomes impossible to describe what makes the file (or class). Each subsequent developer understands that nothing is clear, and boldly adds a new method. The worst thing is CommonUtils(or common_utils.h).

3. Indentation  Nowhere without them. Fortunately, almost all modern IDEs put them down automatically.

4. Names of identifiers   Everything is clear here too. Much has been said about the meaningful names of variables, methods, and classes.
By the way, it’s great to agree with colleagues about the meanings of the words “retrieve”, “fetch”, “get”, “helper”, “utils”, “controller”.

5. Blocks of code   Each method can usually be divided into several logical blocks. For example, checking input parameters, sending a message to grandfather, checking the answer.
It is very convenient to read the code when there is a separator between these blocks. Usually an empty line is enough. The ideal option is an empty line and a couple of words about what will happen in the next block.

6. Description of the fields  Sometimes the name of the field is not enough to reflect its meaning. Then a comment is helpful explaining what's what.
Moreover, I noticed that in the case of a multi-threaded application, it is convenient to indicate which mutex the field is protected (that is, which mutex must be captured in order to change this field).

7. Comments of public methods   Every time I call a method, I am very interested in what this method does, what it expects from the input parameters, and how it can end.
Of course, this may be obvious from the name of the method. However, additional clarifications are sometimes needed. For example, I am very often worried about whether the method will perform an IO operation, whether it will use the processor intensively, or is there any other catch.

8. Lack of commented code  I think everyone has come across this. 5-10 lines of code and stands zakommencheno postscript: Fix for bug 24132.
It seems to me that if the code is not needed, then it should be deleted. To answer the question "where are my favorite 5-10 lines of code?" There is a version control system.

Example

For my taste, this class is very readable:



What do you think?
What other rules do you use? How to make the code more readable?