Coding Conventions Rationale

@0x10 · Регистрация: 24.11.2012

Студворк — интернет-сервис помощи студентам

В повседневной практике мы работаем над разного рода проектами. Будь то суровые enterprise решения, высоконагруженные сервисы или же интерфейсы пользователей, небольшие функциональные прототипы. Мы работаем над коммерческими продуктами или хобби проектами, а может быть и над чисто академическими программами. В любом случае, всегда хочется верить, что труды будут кому-нибудь полезны, а если и пойдут под нож, то станут бесценным опытом.

Но стоит только дать повод - всегда найдутся люди, которые побросают работу и будут поддерживать холивары о расстановке фигурных скобок, пробелов и стиле именования переменных. Тем не менее, я считаю, что есть некоторые соглашения, для соблюдения которых имеются вполне объективные причины. Ниже хочется описать их, немного разбавив вкусовщиной. Быть может, в ответ форумчане вспомнят что-нибудь интересное.

0. Ограничение максимальной длины строки
Какое значение выбрать - дело вкуса, но ограничение должно быть. Указываю это правило под нулевым номером, поскольку несоблюдение нижеизложенных автоматически ведет к невозможности придерживаться этого соглашения.

1. Вертикальное выравнивание
Правило простое - вертикальное выравнивание в коде должно отсутствовать. Если легкость чтения такого кода еще можно назвать субъективной, то поспорить с трудностью поддержки уже сложнее.
Пример.
Пусть имеется вот такой код (взят в одной из тем форума):

C++
1
2
3
4
5
6
int     func
            (
                std::string     const   &   s,
                int                     &   a,
                int                     *   b
            );

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

C++
1
2
3
4
5
6
7
int     func
            (
                std::string     const   &   s,
                int                     &   a,
                int                     *   b,
                std::vector<Instrumental> const & data
            );

Очевидно, что форматирование нарушено. Теперь необходимо выровнять все прочие аргументы для поддержания стиля.

C++
1
2
3
4
5
6
7
int     func
            (
                std::string               const &   s,
                int                             &   a,
                int                             *   b,
                std::vector<Instrumental> const &   data
            );

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

Последствия.
1. Код сложно поддерживать.
2. Стиль не является diff-friendly.
Мы постоянно смотрим диффы. В истории коммитов, в код ревью. Что будет показано людям в случае подобных изменений?

C++
1
2
3
4
5
6
7
8
9
10
11
12
13
14
$ diff -ru first.cpp second.cpp
--- first.cpp   2014-09-25 12:39:17.444961057 +0700
+++ second.cpp  2014-09-25 16:52:10.352839450 +0700
@@ -1,7 +1,8 @@
 int     func
             (
-                std::string     const   &   s,
-                int                     &   a,
-                int                     *   b
+                std::string               const &   s,
+                int                             &   a,
+                int                             *   b,
+                std::vector<Instrumental> const &   data
             );

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

Альтернативный вариант.

C++
1
2
3
4
int func(
    const std::string& s,
    int& a,
    int* b);

C++
1
2
3
4
5
int func(
    const std::string& s,
    int& a,
    int* b,
    const std::vector<Instrumental>& data);

C++
1
2
3
4
5
6
7
8
9
10
$ diff -ru first.cpp second.cpp
--- first.cpp   2014-09-25 16:59:46.396835795 +0700
+++ second.cpp  2014-09-25 17:00:10.996835598 +0700
@@ -1,5 +1,6 @@
 int func(
     const std::string& s,
     int& a,
-    int* b);
+    int* b,
+    const std::vector<Instrumental>& data);

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

C++
1
2
3
4
int func(const std::string& s
    , int& a
    , int* b
);

C++
1
2
3
4
5
int func(const std::string& s
    , int& a
    , int* b
    , const std::vector<Instrumental>& data
);

C++
1
2
3
4
5
6
7
8
9
$ diff -ru first.cpp second.cpp
--- first.cpp   2014-09-25 17:04:39.856833443 +0700
+++ second.cpp  2014-09-25 17:05:00.260833280 +0700
@@ -1,5 +1,6 @@
 int func(const std::string& s
     , int& a
     , int* b
+    , const std::vector<Instrumental>& data
 );

Да, удалось еще сократить дифф на одну функционально незначимое изменение. Цена - повсеместное неестественное форматирование кода. Лично мое мнение: одна "лишняя" строчка в диффе - меньшее зло, чем нарушение общепринятых правил типографии. Читая код, я ожидаю, что как и в текстах книг/статей:
1. Перед запятой отсутствует пробельный символ. После запятой ставится пробел.
2. Знаки арифметических операций отделены одним пробелом с каждой стороны, за исключением унарных операций.
3. Перед открывающей круглой скобкой ставится пробел. После скобки пробел отсутствует. А вот вызов функции уже тяготеет к математической нотации, поэтому в этом случае пробел перед скобкой опускается.

3. Код внутри пространств имен пишется без дополнительного отступа
В пользу этого правила можно приводить различные аргументы. Можно говорить,что нам не нужны дополнительные уровни вложенности. Особенно если в проекте присутствует множество вложенных пространств имен (см ограничение на длину строки). Можно рассуждать о блоках кода и отмечать семантическую разницу между телом функции и телом пространства имен. Но лично мне привычнее опираться на повседневные практики, а как я уже отмечал выше, одна из таких - это использование diff.
Для примера я взял псевдокод алгоритма Дейкстры. Сейчас не важна его компилируемость и прочие элементы стиля, за исключением отступа внутри пространства имен.

C++
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
namespace graph {
 
const int INF = 1000000000;
 
void dijkstra()
{
    int n;
    // ... чтение n ...
    vector<vector<pair<int, int>>> g(n);
    // ... чтение графа ...
    int s = ...; // стартовая вершина
 
    vector<int> d (n, INF),  p (n);
    d[s] = 0;
    set<pair<int, int>> q;
    q.insert(make_pair(d[s], s));
 
    while (!q.empty())
    {
        int v = q.begin()->second;
        q.erase(q.begin());
 
        for (size_t j = 0; j < g[v].size(); ++j)
        {
            int to = g[v][j].first;
            int len = g[v][j].second;
 
            if (d[v] < d[to])
            {
                q.erase(make_pair(d[to], to));
                d[to] = d[v] + len;
                p[to] = v;
                q.insert(make_pair(d[to], to));
            }
        }
    }
}
 
}

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

C++
1
2
3
4
5
6
7
8
9
10
11
12
$ diff -rup first.cpp second.cpp
--- first.cpp   2014-09-25 17:26:57.060822726 +0700
+++ second.cpp  2014-09-25 17:26:51.700822769 +0700
@@ -25,7 +25,7 @@ void dijkstra()
             int to = g[v][j].first;
             int len = g[v][j].second;
 
-            if (d[v] < d[to])
+            if (d[v] + len < d[to])
             {
                 q.erase(make_pair(d[to], to));
                 d[to] = d[v] + len;

Здесь важна четвертая строка:

C++
1
@@ -25,7 +25,7 @@ void dijkstra()

Утилита diff способна показать контекст, в котором были сделаны изменения - имя функции. Понятно, что поиск строки реализован не честным парсингом кода, а поиском ближайшей строки без отступа. Следовательно, если внутри пространства имен код будет с отступом, то максимум, что мы увидим в контексте - это имя неймспейса:

C++
1
2
3
4
5
6
7
8
9
10
11
12
$ diff -rup first.cpp second.cpp
--- first.cpp   2014-09-25 17:31:16.884820644 +0700
+++ second.cpp  2014-09-25 17:31:25.108820578 +0700
@@ -25,7 +25,7 @@ namespace graph {
                 int to = g[v][j].first;
                 int len = g[v][j].second;
 
-                if (d[v] < d[to])
+                if (d[v] + len < d[to])
                 {
                     q.erase(make_pair(d[to], to));
                     d[to] = d[v] + len;

Учитывая, что функций в пространстве имен может быть N, этой информации недостаточно для быстрого определения контекста.

Справедливости ради стоит отметить, что для поиска функции diff может использовать регулярное выражение, но в этот момент у меня включается лень: ни писать, ни гуглить регулярку для этого случая не хочется.

Других правил оформления кода, обусловленных практическими потребностями, мне пока не вспоминается. Если есть идеи - welcome.

@sourcerer · 06.10.2016, 20:30

Сообщение от Mr.X

Неужели это можно прочитать?!

Можно.

Сообщение от Mr.X

А в обратную сторону он умеет?

Не знаю. Вроде бы, нет.

Добавлено через 12 минут

Сообщение от Mr.X

Да, непарные скобочки особенно впечатляют!

Я лично отформатировал бы так

C++
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
// 1.
 
//У вас имеются два билета. Номер первого билета равен M, второго – N.
//Лимиты M и N: 10000000 ? M < N ? 99999999.
//Ваша задача определить количество "счастливых билетов" в данном диапазоне.
//Билет "счастливый", если сумма первых 4 цифр равна сумме последних 4 цифр.
//Ввод:
//Вводятся номера двух билетов.
 
//Вывод
//Количество "счастливых билетов" в данном диапазоне.
 
//Пример:
// a: 11111110
// b: 11111112
// ans: 1
 
// a: 10000000
// b: 99999999
// ans: 4379055
 
#include <algorithm>
#include <cmath>
#include <iostream>
#include <map>
 
typedef long long T_int;
typedef std::map <T_int, T_int> T_count_of_sum;
 
T_int sum_digits( T_int n )
{
    T_int res{};
    
    do
    {
        res += n % 10;
        n /= 10;
    }
    while ( n );
    
    return res;
}
 
void fill_count_of_tail_dig_sum
    (
        T_int min,
        T_int max,
        T_int mod,
        T_count_of_sum &count_of_sum
    )
{
    for ( T_int n{ min }; n <= max; ++n )
    {
        ++count_of_sum[ sum_digits( n % mod ) ];
    }
}
 
T_int winning_tickets_count_in_segment
    (
        T_int min,
        T_int max
    )
{
    T_count_of_sum count_of_sum_L;
    T_count_of_sum count_of_sum_R;
    T_int num_len = std::to_string( max ).size();
    T_int mod = std::pow( 10, num_len / 2 );
    
    fill_count_of_tail_dig_sum
        (
            min / mod,
            max / mod,
            mod,
            count_of_sum_L
        );
    
    fill_count_of_tail_dig_sum
        (
            min,
            std::min( min + mod - 1, max ),
            mod,
            count_of_sum_R
        );
    
    T_int res{};
    
    for ( T_int sum{}; sum <= 9 * num_len / 2; ++sum )
    {
        res += count_of_sum_L[ sum ] * count_of_sum_R[ sum ];
    } // for
    
    return res;
}
 
int main()
{
    T_int a{};
    T_int b{};
    
    std::cin >> a >> b;
    
    std::cout << winning_tickets_count_in_segment( a, b ) << std::endl;
}

@Mr.X · 06.10.2016, 20:39

Сообщение от gru74ik

Можно.

Не верю! Вот, по сравнению с этим извращением, мой стиль - просто верх невинности!

Сообщение от gru74ik

Вроде бы, нет.

Ну вот, ни на что толковое он таки не годен!

Добавлено через 8 минут

Сообщение от gru74ik

Я лично отформатировал бы так

Сообщение от gru74ik

C++
1
res += count_of_sum_L[ sum ] * count_of_sum_R[ sum ];

Т.е., по-вашему, это более читаемо? Чем мотивируете?

@sourcerer · 06.10.2016, 21:06

Сообщение от Mr.X

Т.е., по-вашему, это более читаемо? Чем мотивируете?

Ничем. Я художник, я так вижу. Макконнелл, правда, видит так же, но это так, к слову. Вы делайте как хотите. Свой код форматирую так, как хочу. В IT-корпорации всё равно все поголовно будем соблюдать корпоративный кодстайл.

Байт · 06.10.2016, 21:32

Сообщение от gru74ik

Я художник, я так вижу.

Золотые слова!

@Ghost Writter · 07.10.2016, 01:33

Сообщение от gru74ik

Ничем. Я художник, я так вижу. Макконнелл, правда, видит так же, но это так, к слову. Вы делайте как хотите. Свой код форматирую так, как хочу. В IT-корпорации всё равно все поголовно будем соблюдать корпоративный кодстайл.

gru74ik, "Макконнелл, правда, видит так же, но это так, к слову."

Чой-то?) Вот дочитываю его книгу. Там везде верблюжийСтиль. И вообще там не одна глава на эту тему.

@sourcerer · 07.10.2016, 06:49

Сообщение от Ghost Writter

Чой-то?)

Той-то. Я про отступы внутри квадратных и круглых скобок говорил. Нижние_подчёркивания или верблюжийСтиль - про это вообще речи не шло.

Croessmah · 07.10.2016, 07:54

Сообщение от Mr.X

Неужели это можно прочитать?!

Большей частью пользуюсь именно

C++
1
2
some {
}

а не

C++
1
2
3
some
{
}

меня второе вообще бесит.

@Martein · 07.10.2016, 08:17

Mr.X,, Я долго ждал, когда его стайл коллективно забросают какашками. Да, и в обратную сторону он умеет. Просто берёте сайт https://clangformat.com/ и создаёте свои правила, а потом генерируете файл конфигурации для этого своего стайла и прикручиваете к clang-format, но я очень надеюсь, что у вас не получится. =)

@sourcerer · 07.10.2016, 09:22

Сообщение от Mr.X

А в обратную сторону он умеет?

Тут мне Martein подсказал - он по всякому умеет. Как настроите, так и будет.

Добавлено через 55 секунд
Martein, опередил меня

@hoggy · 08.10.2016, 23:34

Сообщение от Ghost Writter

Чой-то?) Вот дочитываю его книгу. Там везде верблюжийСтиль. И вообще там не одна глава на эту тему.

такое впечатление, что вы не въехали ни в то,
о чем вам писал господин gru74ik

ни в то, о чем пишет господин Макконелл.

Сообщение от Croessmah

меня второе вообще бесит.

а мне уже пофигу, что так, что этак.
главное что бы не такое уг, как у господина Mr.X

@Ghost Writter · 09.10.2016, 09:00

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

В книге то Макконелл использует

C++
1
2
3
SomeName(){
     //....
}

Хотя это больше напоминает, если бы писал на Java (ток имя метода с нижнего регистра начинается). Там видимо, из-за специфичных языку элементов удобно так писать.

В большинстве примеров из книг и статей на C++ я видел такое форматирование:

C++
1
2
3
4
someName()
{
     //....
}

И оно мне поудобнее будет. Хотя Макконелл приводит рассуждения, что так нельзя выделить управляющую структуру.

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

Такой код можно встретить в студии используя проекты C#

C#
1
2
3
4
SomeName()
{
     //....
}

Я был бы рад, если кто-т просветит в этом деле, потому что опыта написания больших проектов у меня нет. Если подскажите - буду рад.

Croessmah · 09.10.2016, 10:05

Сообщение от hoggy

а мне уже пофигу, что так, что этак.

Мне тоже, код Mr.X тоже нормально читаю,
но всё же хочется хорошего для себя.

@hoggy · 09.10.2016, 11:44

Сообщение от Croessmah

код Mr.X тоже нормально читаю

я его код вообще не читал)))
даже не пытался.
как глянул на "это", сразу подумал: "а оно мне вообще надо?"

Новые блоги и статьи Все статьи Все блоги /
Мобильное приложение ColorStep pavlinmavlin 17.09.2026 Реализовал приложение Красный, Зеленый, Синий в Unity3d + c#. Название изменил на ColorStep. Приложение прошло модерацию и теперь доступно для скачивания. Делал его сам, шаг за шагом — и вот,. . .	Запрет дублирования строк в табличной части Maks 13.09.2026 Реализация из решения ниже выполнена на нетиповом справочнике "Нормы ТО" с табличной часть "Виды ТО", разработанного в КА2, со следующими реквизитами: - ВидТО (СправочникСсылка. ВидыТО); - ВидГСМ. . .	Скрипты Tampermonkey для CyberForum, ChatGPT, Claude и пр. Jin X 06.09.2026 Скрипты Tampermonkey для CyberForum, ChatGPT, Claude и пр. Работая с форумом и нейросетями в браузере часто хочется что-то подкорректировать или добавить какого-то функционала. Ниже прикреплён. . .	Программа опроса у.з. расходомера SLS-720F Argus19 02.09.2026 Программа опроса у. з. расходомера SLS-720F Программа опрашивает один раз в минуту три ультразвуковых расходомера SLS-720F через интерфейс RS-485 по протоколу Modbus RTU. Опрашиваются регистры. . .
Hyper-V: Компьютер должен поддерживать доверенный платформенный модуль 2.0. Maks 31.08.2026 При установке Windows 11 на виртуальную машину Hyper-V 2-го поколения вылезла такая ошибка: Решение: в параметрах виртуальной машины, в разделе "Безопасность" (Security) активировать флаг. . .	Архитектура биовида Стива в Майнкрафте: Зачем бонобо кубический каннибализм anaschu 30.08.2026 Кубический Вагинокапитализм в Minecraft: Математический инвариант ОДУ и рок Стивов-бонобо Главная задача разработанной «Модели Всего» — наглядно продемонстрировать наличие системной «судьбы». . .	Оттачиваю умение писать js программы. russiannick 30.08.2026 Проектом выходного дня стало написание Книги шифров Виженера. Итогом стала версия 200, синий туман. Синий туман назван так, потому что замораживает текст под собой. Нажатие синих кнопок управляют. . .	мат медиц модель 30. презентация проекта anaschu 27.08.2026 хоп хоп хоп хидахоп, а я кладую))

@Martein 704 / 109 / 21 Регистрация: 22.06.2014 Сообщений: 241
	07.10.2016, 08:17
	Mr.X,, Я долго ждал, когда его стайл коллективно забросают какашками. Да, и в обратную сторону он умеет. Просто берёте сайт https://clangformat.com/ и создаёте свои правила, а потом генерируете файл конфигурации для этого своего стайла и прикручиваете к clang-format, но я очень надеюсь, что у вас не получится. =) 2