How to write beautiful and readable code?

The first thing I would like to say is a very good question.

What you are looking for is called a code writing convention (or code writing standards ), and they are easy to find by searching for "coding style convention" or "coding standards". For C / C ++ there are several conventions, what specific you will use - as a rule, it does not matter, the main thing is that the whole project be in one key. The first references are conventions from Google (C ++) and GNU with Linux Kernel (C) - I have not read them, but they should fully cover the above questions.

As for the comments, this is a rather controversial position, here you have to work out your strategy. Many believe that the code should be read by itself without comment; people like me support this strategy, but they believe that comments should maximize chewing on possible use (in order to be trivially highlighted in the IDE).

I write in PHP, Python and Javascript, but still I allow myself to leave a couple of conjectures (they relate to your 2nd point). This item brought my team a lot of trouble, after the project grew.

We have an internal protocol (JSON over TCP), with which the components of the system communicate with each other, let's call it, let's say ... TMP-protocol.

There are more than a dozen entities that are directly related to TMP - all sorts of interfaces, gateways, callbacks, "promises", waiting for an answer, etc. and so on.

NEVER give names to classes and variables that do not give a rough idea of ​​their purpose, for example :

 class TmpProtocol 

Protocol in this case is an extra 8 characters (tmp is already a protocol), the class name doesn’t mean anything at all. Compare with this :

 class TmpClientGateway 

It is better? Much more Intuitively, I want to do something like this:

 $a = new TmpClientGateway(); $a->makeRequest(...) 

Now about the variables. If a variable has at least some value in the outside world, then it needs to be given a meaningful name, for example, the following code will turn the head and bring you to nausea:

 self.deferred = defer.Deferred() 

We promised someone (no matter to whom) a pending result. But what we have promised is not clear to anyone (and you yourself will forget in a year). Where better to write something like this:

 self.serverResponse = defer.Deferred() 

You need to give yourself an account of what this particular thing does and call it appropriately. And a jumble of classes serving tmp:

 class tmpProtocol, class Handler, class tmpInterface 

turns into something more understandable:

 class tmpServerRequest, class tmpServerRequestFactory, class tmpMethodDecorator 

And yet, if a certain class is a successor from some standard Factory, then the variables of this new class in the name should contain Factory, and not, say, Handler

Now about the 3rd item: Do not force the same piece of code to handle the error of the tcp connection and the error of, say, "incompleteness" of the incoming data (even if from above, for the user, these situations look the same).

This will make the code completely opaque. It is much better to spread the functionality across two, even if almost identical, functions and avoid obscure branching from if-else-elsif-elsif.

Especially maddening, when something almost the same happens in the body of elsʻov, but different, by 1 line (in one place - manually closed, socket, and in the other - did not begin to do it).

It will be much clearer if the first situation is handled by the errCorruptedData function (the data came, but the curves, so close the socket!), And the second situation is errNoRouteToHost (the socket did not open anyway).

I apologize for the degenerate examples.

The quality of your C code mainly depends on your practical experience and the degree of enlightenment. In addition, each major project has its own formatting quirks.

Therefore, I will answer the points of the question, using the secret (no longer) convention, which I usually use when I write C code.

1. Two or more use a for (c). I shorten it only if it can be used to automate the whole process. I never allow Chinese code.

2. I always use long and clear lower case identifiers separated by _ of which the context and all the additional information is immediately clear. Never cut them. very_long_clear_and_useful_variable_name . I never use Hungarian notation with type information in the identifier.

3. I create as many of the most appropriate abstractions as needed to solve the problem, not more. I also follow the hard rule of thumb if possible: A non-automatically generated function that has either lines longer than 80 characters, or more than 3 levels of nesting of control flow instructions, or more than 3 nested parentheses in one line, or more than 40 lines, or receiving more than 3 parameters (variadic counts as 1), or in the code of which there are more than 0 explicitly written numbers or string constants with probability bl viscous to 100% no use to anybody in the outside world and will fit only as a case study or for a neat internal use.

   Every time you insert a function into the production that does not satisfy the rule, one star in the sky goes out, a crowd of sadistic schoolchildren dissects a hamster alive, and neurons die in the minds of your colleagues reading it.

4. In general, I do not use comments in the definitions, instead of them I do a forced upload to the debag log. In the ads I insert only the header and a brief description of what this file does.

5. МАКРОСЫ large letters, everything else is small through _. I use K & R otsupy. DeprecatedCamelCaseIdentifiers do not use DeprecatedCamelCaseIdentifiers . I use the _t suffix to distinguish structures declared from typedef from the rest.

Although of course how many conventions do not apply With the code in general is quite difficult to make easy to read.

In confirmation of this, you can watch the international competition of the most complicated programs in C.

Here, for example, is a typical program from there that simply draws a huge smiley showing the language in the terminal:

 m(f,a,s)char*s; {char c;return f&1?a!=*s++?m(f,a,s):s[11]:f&2?a!=*s++?1+m(f,a,s):1:f&4?a--? putchar(*s),m(f,a,s):a:f&8?*s?m(8,32,(c=m(1,*s++,"Arjan Kenter. \no$../.\""), m(4,m(2,*s++,"POCnWAUvBVxRsoqatKJurgXYyDQbzhLwkNjdMTGeIScHFmpliZEf"),&c),s)): 65:(m(8,34,"rgeQjPruaOnDaPeWrAaPnPrCnOrPaPnPjPrCaPrPnPrPaOrvaPndeOrAnOrPnOrP\ nOaPnPjPaOrPnPrPnPrPtPnPrAaPnBrnnsrnnBaPeOrCnPrOnCaPnOaPnPjPtPnAaPnPrPnPrCaPn\ BrAnxrAnVePrCnBjPrOnvrCnxrAnxrAnsrOnvjPrOnUrOnornnsrnnorOtCnCjPrCtPnCrnnirWtP\ nCjPrCaPnOtPrCnErAnOjPrOnvtPnnrCnNrnnRePjPrPtnrUnnrntPnbtPrAaPnCrnnOrPjPrRtPn\ CaPrWtCnKtPnOtPrBnCjPronCaPrVtPnOtOnAtnrxaPnCjPrqnnaPrtaOrsaPnCtPjPratPnnaPrA\ aPnAaPtPnnaPrvaPnnjPrKtPnWaOrWtOnnaPnWaPrCaPnntOjPrrtOnWanrOtPnCaPnBtCjPrYtOn\ UaOrPnVjPrwtnnxjPrMnBjPrTnUjP"),0);} main(){return m(0,75,"mIWltouQJGsBniKYvTxODAfbUcFzSpMwNCHEgrdLaPkyVRjXeqZh");} 

She is quite working. What kind of convention is there?

PS To make it a little easier to understand complex ads like this:

char **(*(*(*x)[100])(int,char*,double ***,void(*)(int**,char[])))[50];

In fact, everything is simple and clear. x is just a pointer to an array of 100 pointers to a function that takes arguments ( int , a pointer to char , a pointer to a pointer to a pointer to a double , a pointer to a function that accepts (a pointer to a pointer to an int , an array of char ) returns void ) that returns a pointer to an array of 50 pointers to char pointers

you can use their English translator

First of all, I must say that there is no answer to this question. On both its parts ...

The concept of beauty is generally irrelevant to code. The code can not be beautiful. This is not a poem, and not prose. And it should not be beautiful. His task is not to give someone aesthetic pleasure, but to compile. He has a purely instrumental function. Surely, there are people who enjoy various designs of cycles and conditional operators purely aesthetically, but this is rather a perversion ... no need to focus on such people. Although it should be noted that the algorithm that is implemented in the code can be beautiful. But these things must be clearly separated. To call some code beautiful is the same as to call beautiful reinforced concrete from which a beautiful building is built.

As for the readability of the code, then this is better. Although there is no answer to this part of the question either. In the industry, there is a widespread erroneous view that readability is a property of the code itself ... as if the code can be given such a form that makes it readable. In fact, it is not. The code cannot be read by itself ... apart from who reads it. This is a more or less obvious thought. But, unfortunately, few people think about it. In fact, you need to think about the readability of the code not as a property of the code itself, but as a relationship between two or more people, which is somehow embedded in the code that they write and read. If each of these people turns out to write code so that others can read and understand it more or less comfortably, then these people write readable code. But this readability is inextricably linked with these particular people. You can not pass the code to other people, while maintaining its readability at the same level. Other people in the brain will have already formed completely different patterns associated with the code, and therefore the readability of any code that does not fit into them will surely squeeze.

The notorious Coding Style Guides actually approach the solution of the problem from the people. Their task is only to fix a certain set of reasonable rules that people working together agree to adhere to. Not because these rules are objectively good by something, but simply because such a set of rules is most convenient for them as a general one.

In paragraph 4, the essence of the problem is very accurately grasped, although it is about comments. "Your code is always clear." - This phrase needs to be mentally repeated three times whenever there is a desire to make a judgment about your own code. Including its readability. Well, or you can slightly change the phrase: "We always read our code."

In general, apart from any connection with people, the code can be given only such properties as correctness, compilability, efficiency, etc. The property of readability exists in the code in the form of something ephemeral that associates this code with some specific people. And in order to evaluate the code for readability, you need to show it to other people. And not just to other random people, but to those who have a personal interest in reading and understanding it. There is no other way. If the code is interesting only to the author himself, and he can read it comfortably himself, then the code is already 100% readable. Nothing more needs to be done. It is impossible to increase readability above 100%.

Each language has its own approach. For the same C and C ++, the answer to some items may be completely different.

1. Reducing the amount of code is sometimes a plus, because Rummaging through the colossal codebase is often unpleasant, and measuring the number of KLoCs in your projects is a silly thing. But we must not overdo it. We have here, you know, not code-golf =) the code should always be readable, even for the person who sees it for the first time!

2. Variable naming. This is a matter of taste, but it is important that the variable name provides at least some information about what it is.

3. IMHO is the most important point, I'll sign here (a little more than asked, but oh well) with specifics for C, because I have some experience with him. Some of this applies to other languages. I warn you in advance, everything further is purely my IMHO.

   In any C code, the main thing is balance.

   It is important to keep a balance between the desire to make the code more modular and reusable, adding more specialized functions to it, and creating too long, non-optimal and certainly unreadable chains of function calls (not all C compilers are able to inline, not the rubber stack, and the frames are not instantaneous are created).

   There must be a balance between what your API takes over and what it puts on the user (the calling API code). For example, there is an unspoken rule - if the API initializes the newly created object, the memory allocation for this object should be left to the user.

   The balance should be between the number of functions, globals, function prototypes and macros in one file (and in one translation unit). On the one hand, it’s not very good to tamper either the file or the translation unit, but on the other hand, it’s not reasonable to create a separate file for one function.

   And, of course, the balance should be between what is visible to whom and where. If someone tells you that there is no encapsulation in C, do not believe, it was there long before C ++ and its private modifier! =) Чтобы энкапуслировать функцию или global, объявите ее статической ( static ) в отдельном translation-unit-е, тогда к ней можно будет получить доступ только из него же. Чтобы энкапуслировать членов структуры, используйте ее как opaque pointer - это можно сделать, например, объявив ее как incomplete type в коде, вызывающем энкапсулирующее API, а определить ее уже в самом API (хороший пример тут ).

4. Комментарии - это хорошо. Но нельзя на них слишком сильно полагаться. Если код плохо написан, то тут никакие комментарии не спасут. Опять же, нужен баланс - комментариев не должно быть мало (за исключением очень редких случаев, когда код благодаря красноречивым именам функций/переменных и т.д. и логичного построения алгоритмов читаем сам по себе), но и не должно быть много (как в поговорке: 90% комментариев, 10% кода , но все равно нихрена не понимаю, что этот код делает ).

5. Стиль - это лично ваше дело. Конечно, у некоторых языков есть идиоматический стиль, которого стараются все придерживаться (например, C# с майкрософтовским стилем, или Java со стилем примеров из Javadoc). Проблема в том, что у C их что собак нерезанных. Кто-то пишет код, как в примерах в книге K&R, кто-то следует формату Linux Kernel - а, кто-то предпочитает формат Столлмана... Вот здесь энное количество примеров кода разных стилей. Вообще, стиль себе каждый программист должен выбрать сам (лично я, например, даже на C пишу на чем-то сродни стилю Javadoc-а, с camelCase-ом и индентацией, похожей на BSD KNF). И, конечно, на каждом себя уважающем предприятии есть свой, иногда уникальный, style-guide, определяющий, КАК должен выглядеть код, так что надо уметь адаптироваться к другим стилям.

Буду отвечать общими принципами - они сами подходят к Си++, но примеры буду приводить те, которые приходят в голову, не обязательно на плюсах.

1. Код должен быть кратким. Но не максимально.
   Например, я как-то переписал несколько экранов разметки на несколько строк (html, AngularJS). И добавил комментарий, описывающий, что там вообще происходит.
   А вот пример на VB.NET, когда сокращение кода - это жесть:
   X *= 10 - 5 значащих символов
   X &= 0 - 4 значащих символа и жуткий оверхед при выполнении: сначала мы конвертируем числа X и 0 в строки, потом создаём новую строку выполнив конкатенацию, потом парсим получившуюся строку обратно в число и выполняем присваивание. Место такому коду - только в codegolf-задачках, больше нигде.
   В чрезмерно ужатом коде разобраться может быть очень сложно, а уж на Си++ - особенно.

2. На мой взгляд, имена переменных должны быть краткими. Но при этом осмысленными. И без излишних сокращений. Да, я могу понять, что такое s2e в <a id=s2e>Switch to English</a> , но на мой взгляд, такие сокращения оправданы только для частоиспользуемых вещей, а в остальных случаях их применять не следует. И я не люблю распространённые сокращения tmp и cnt - эти 1 - 2 символа не стоят того.

3. Всё по ситуации. Если есть осмысленный блок, который хочется вынести в функцию - то да. Если нет, то не надо. Если вынесение вызывает проблемы, то тоже не надо. Как вариант - написать комментарий, что делает конкретный участок кода и поставить обрамляющие этот участок фигурные скобки, чтобы блок был выделен явно:

    // Сделать что-то  {  ТутКакойТоДлинныйКод();  } 

   Чрезмерное выделение функций на каждый чих мне не нравится. Да, некоторые любят, когда код можно читать как текст, но код обычно читают не чтобы полюбоваться, а чтобы что-то в нём изменить. И искать нужное место, когда перед тобой почти текст, а не код мне очень неудобно.

4. Комментарии должны говорить об идее кода или пояснять какие-то сложные моменты. Пояснять то, что можно понять из кода, обычно не стоит. Единственное исключение, это когда код делает что-то совсем неочевидное. Имеет смысл пояснять какие-то подводные камни и ограничения, а так же высокоуровневые описания. Имеет смысл отмечать комментарием то, что при первом взгляде кажется ошибкой. Например, присваивания в условиях и отсутствие break в switch'е.

5. Про заглавные буквы комментировать не буду.
   Что касается отступов - почти всегда пропускаю строку перед и после блоками.
   Предпочитаю не ставить фигурные скобки: https://ru.stackoverflow.com/a/424351/178988 .
   Не пишу несколько операторов в одной строке просто так.
   Допускаю возможность использования запятой.
   Если есть основания выровнять похожие строки столбцами - делаю это. Это единственный случай помещения нескольких операторов в строку.