Formatting source code

Правильное форматирование кода действительно важно, если хотите чтобы код был легко-читаемым и был понятен не только вам. For example, студенты одной группы, которые читают одинаковую литературу по программированию, которым программирование преподает один и тот же человек, всё равно решают задачи разными способами. При этом у каждого свой особый стиль форматирования кода.

Если вы когда-либо пытались читать чужой код, то замечали, что необходимо некоторое время, чтобы перестроиться и начать понимать, как работает этот код и что он реализует. Of course, писать код можно по-разному, в том числе не совсем читабельно, и что самое интересное, программа будет замечательно работать. Вот посмотрите на этот код:

Он полностью рабочий и никаких проблем при его выполнении не происходит. Но искренне жаль того программиста, которому «в наследство» достанется программа, написанная таким образом, и которому надо будет в эту программу что-то добавить или усовершенствовать её. Это еще хорошо, что в данной программе переменным даны осмысленные имена, but not int a, int b. Хотя программа очень простая, она очень плохо читается. Другое дело если она будет написана с использованием правил стандартов форматирования кода и соглашений о кодировании – с пробелами, отступами, переносами строк, комментариями:

You can see how much easier to read and understand the code became.

Практически всегда, над созданием одной программы работают несколько программистов. При этом сопровождать программу в дальнейшем может уже другая группа программистов. Становится очевидной необходимость создания единого стандарта кодирования. If programmers will adhere to these standards when writing code - all of it will look the same, which at times make it easier to work on group projects. Зачастую контора сама вырабатывает свой собственный стандарт кодирования (coding convention), но есть распространенные стандарты. К ним относятся, for example:

Google C Style Guide

Coding Standards IBM

Linux kernel coding style

Full version Agreement on the coding in C ++ in English here.

If посмотреть статистику использования стандартов форматирования кода, становится очевидным, что большинству программистов есть еще над чем работать и к чему стремиться. Ведь больше половины из опрошенных, либо используют свой собственный стиль кодирования, либо вообще не знают, зачем стандарты форматирования и соглашения о кодировании созданы.

Поговорим о содержании стандартов и соглашений.

Основными задачами всех стандартов и соглашений о кодировании является способствование:

-написанию легко-читаемого кода, понятного для всех;

-написанию безопасного кода (ведь эти стандарты были созданы программистами-практиками, которые знают, какие ошибки может повлечь за собой неправильное оформление кода);

-единообразного кода (у всех структура кода выглядит схоже).

Просмотрев несколько стандартов и соглашений, можно увидеть, что в основном внимание уделяется следующим пунктам:

имена переменных, констант, function, classes

Главное при объявлении переменной (functions, класса и т.д.) – дать осмысленное имя, как можно ближе к контексту использования. Let's, в вашей программе определено больше 20-ти переменных, и всем дано имя в виде буквы алфавита. Agree, даже вам, создателю этой программы, будет тяжело работать с этими переменными. Не говоря уже о том, что нужно так же помнить какие данные хранит каждая из них. Гораздо легче работать с переменными, имеющими обоснованные имена:

age – возраст;
number – номер;
amount – количество;
name – имя.

Желательно имена писать не английским транслитом, а английскими словами.

не vozrast – а age;
не kolichestvo – а amount.

Если вы не знаете перевода, воспользуйтесь одним из множества онлайн переводчиков. At the same time fill up your vocabulary. rules, according to which are the names of variables, It can be read in our article Data types, variables and constants in c++.

Constants recommended to assign names or consisting of uppercase letters (HOURS_IN_DAY, SIZE) либо каждое новое слово с большой буквы, как Google C Style Guide (kHoursInDay). Говоря о константах, их советуют использовать везде, где только можно. Не объявляйте переменные хранящие количество дней в неделе и месяцы в году – объявляйте константные переменные в таких случаях. Относительно функций – если функция не изменяет аргумент, передаваемый по ссылке или по указателю, то аргумент должен быть константой.

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

printData(); – печать данных
enterName(); – ввод имени
showStr(); – показать строку

В имени класса первая буква должна быть заглавной:

class Employee
class Point

Если имя состоит из нескольких слов, написать его можно разными способами.

– каждое новое слово с большой буквы (верблюжий регистр): boxWithApple, amountBoxesForSale

– использовать нижний прочерк между словами: box_with_apple, amount_boxes_for_sale

Не бойтесь давать сложные имена. In the environment Microsoft Visual Studio обращаясь, к объявленной переменной (начиная вводить ее имя), вам будет предложено выбрать имя из выпадающего списка. Giving too long names is not worth. It is really capture the essence of a variable in a few words.

Сразу хочу рассказать о «венгерской нотации» – соглашении об именовании переменных и других идентификаторов в коде программ. Суть «венгерской нотации» в том, что имя переменной (functions, массива и т.д.), начинается с префикса, состоящего из одной или нескольких букв. Приведу несколько примеров объявления имен идентификаторов с префиксами:

int iAmount или nAmount,

bool bChoice,

int aNumbers (a говорит о том, что aNumbers – This is an array of),

string sName (string),

int* pArr (от слова pointer – pointer)

Когда мы встретим такое имя в коде, то его префикс будет говорить нам о том, что это за идентификатор и какие данные он хранит.

фигурные скобки

Some agreements and standards recommended to use curly braces in an if block, else, while, do, for даже если они содержат всего одну строку либо не содержат ничего. For example:

Каждую фигурную скобку желательно располагать в отдельной строке. Так очень легко проследить, где блок начинается и где заканчивается.

пробелы в строке и отступы между строками

Рекомендуется не использовать пробелы в конце строки перед оператором точка с запятой.

При использовании оператора присвоения значения пробелы необходимы с обоих сторон от этого оператора:

Это же касается и операторов используемых в арифметических выражениях:

Applying unary operators, пробелы не нужны:

Многие используют табуляцию в строках, чтобы визуально выделить некоторые блоки кода. For example it looks like the code fragment вложенными циклами с использованием табуляции:

and so without:

По поводу отступов между строками кода, basic principle comes down to, чтобы минимизировать их количество. Логика в том, что чем больше код, который умещается на одном экране, тем легче проследить и понять работу программы. Поэтому не используйте больше одной-двух пустых строк между блоками кода или функциями.

комментирование кода

К сожалению, многие не любят комментировать код, although comments play an important role in maintaining the readability of the high-level code. Как написано в Google C Style Guide «Комментарии важны, но лучше когда код сам говорит за себя. Давать осмысленные имена переменным гораздо лучше, чем давать непонятные названия и затем раскрывать их суть в комментариях»

Оставлять комментарии в коде можно либо используя двойной слэш // (комментирование одной строки), or /* comment */ . Вторым способом можно оформить многострочный комментарий. But some authors prefer the standards offered to give all the commenting using a double slash // .

Каждая функция должна иметь комментарии непосредственно перед ней, которые описывают то, что делает эта функция и как её использовать. For example, перед функцией можно написать: // Открывает файл, or // печатает данные

Так же желательно, чтобы каждое определение класса имело сопроводительный комментарий, описывающий, что это такое и как его следует использовать.

В стандартах форматирования кода можно почерпнуть еще много чего полезного для формирования собственного хорошего стиля программирования. Всего в данной статье не перечислишь. Поэтому постарайтесь найти время и почитать некоторые первоисточники, references to which have been given above in the article. I recommend also to check on the system of documenting source code Doxygen.

Хочу обрадовать тех, кому все же придется столкнуться с кодом, написанным подобно первому листингу в этой статье. In a development environment Microsoft Visual Studio 2013 Express (perhaps, и в более ранних версиях) есть “спасательная комбинация клавиш” Ctrl K затем Ctrl F, нажав которую осуществится форматирование выделенного исходного кода. То есть если выделить неотформатированный код и нажать эту комбинацию клавиш – автоматически добавятся и необходимые пробелы, и отступы, и скобки перенесутся в отдельные строки. В общем станет код выглядеть, как для людей.

Применяя на практике форматирование кода, описанное в стандартах и соглашениях о кодировании, вы добьетесь и достойной легкой читаемости кода, и его безопасности. Этим вы облегчите работу и себе и коллегам по проекту. Perhaps, даже кто-то скажет вам спасибо. А я говорю спасибо моему знакомому – for author “Блога программиста” pro-prof.com за то, что предложил и помог мне написать статью на данную тему.