Пролог
В некоторых организациях, в которых программируют микроконтроллеры есть свой внутренний стандарт оформления Си-исходников (сорцов). Как правило там обычно есть разумные пункты. Однако в этом тексте я перечислил самые нелепые и абсурдные требования и рекомендации оформления сорцов, которые реально присутствуют в современных российских электронных организациях, где программируют микроконтроллеры.
Это требования категории, мягко говоря, "зачем?". Вот буквально несколько реальных примеров из жизни. Это просто диктатура абсурда, парад нелепости. Формализм при ревью уже перешёл все рамки здравого смысла. Наш code style - это бег на месте.
1. Запрет установки программ, запрет открытия диспетчера устройств, запрет открытия диспетчера задач, запрет прописывания переменной PATH на локальных PC. Пароль руководителя отдела на изменение яркости монитора. Всё только через пароль руководителя отдела!
2.Запрет на использование оператора switch(). Вместо этого делать лесенку из if() {}else if(){}....
38--Всегда определять константы после определения типов данных (структуры и прочее). Абсурд в том, что внутри типов данных-структур обычно могут быть перечисления (так в SDK у всех вендоров микроконтроллеров). А перечисления - это именованные константы. И поэтому константы надо определять до определения типов структур. Чтобы избежать этого у нас в компании решили просто запретить использование перечислений (enum).
2. Собирать код только мышкой из-под GUI-IDE (IAR или KEIL) и никаких там скриптов сборки (Make, CMake)! У нас зарплатный фонд такой, что мы можем нанять только студентов, а они умеют программировать только в IDE. Мышкой.
36. В конце каждого блока if(...) {...} ; xxx(...) {...} ; for(...) {...} и т.п. необходимо пиcать комментарий // end of if(...). // end of xxx(...) // end of for(...) соответственно. Правило обязательно к применению, если блок с фигурными скобками охватывает больше чем 3 строчки кода, а для функций правило обязательно во всех случаях!
3. Строгие правила расставления отступов к коде и вообще искусственно выдуманное форматирование кода, которое даже опциями clang-format или GNU-indent выставить невозможно. Только ручное расставление отступов!
4. Строгие правила оформления шапки текста перед каждой функцией. Не дай бог поставишь лишний пробел!
5. Писать очевидные текстовые комментарии к каждой строчке Си-кода. Не важно, что по именам переменных и функций и так всё ясно. Это тоже, что на домашнего кошака прилепить надпись "это кот".
6. Строгий запрет на использование битовых полей в языке программирования Си.
7. Строжайший запрет на использование объединений (union) в программах Си .
8. Строжайший запрет на использование перечислений (enum) в языке программирования Си!
9. Каждая конфигурационная константа должна иметь комментарий с "Valid values", в котором описано множество возможных значений данной константы. Перечисления (enum) же запрещены, поэтому надо как-то выкручиваться, через эти текстовые комментарии.
10. Запрет на использование стандартных типов данных из файлов <stdint.h> <stdbool.h> (bool, uint32_t, int8_t и проч.)
11. Первая строка файла должна содержать комментарий "start of file"
12. Предпоследняя строка исходного файла должна содержать комментарий
"//****end of file*******"
Как мне сказал автор требования: "Это чтобы посылать код сообщением в текстовом мессенджере и чтобы было понятно, где заканчивается файл". Как вам такая аргументация?
13. Настройки компоновщика хранить прямо в папке с проектом. И так для каждого проекта с одним и тем же микроконтроллером. Получается дублирование конфигов для компоновщика.
14. Использование кода сторонних библиотек запрещено! Никакого FreeRTOS, CMSIS, FatFs, HAL от официального производителя микроконтроллера! Любое Third Party запрещено!
15. Все аргументы функций должны быть перечислены "в столбик". Везде и всегда!
"Гениальность" этого стилистического требования в том, что его невозможно выставить автоматически утилитой clang-format. Это требование также невозможно выставить такими авто форматировщиками, как Artistic Style и GNU Indent.
Кто-то как будто специально выдумал это аутистское форматирование кода в столбик, чтобы саботировать разработку ПО во всей организации. Другого объяснения, тут придумать, простите, но просто нереально....
16. Для всех объявлений глобальных функций в h-файле обязательно ключевое слово extern! Не важно, что и без extern код собирается и работает. А само слово extern только для переменных введено в язык C.
Кстати, а зачем в самом деле надо писать extern у прототипов функций в .h?
17. Порядок объявления функций должен совпадать с порядком определения функций.
Это подрывное правило исключает возможность создания большого количества маленьких Cи-функций, которые помещаются на один экран.
Дело в том что штатным программистам лень потом вручную сортировать функции по порядку объявления. Из-за этого правила программисты предпочитают создавать 3, максимум 5 - мега функций-богов по тысяче строк в каждой, которые делают всё. И это убивает модульность, читаемость, тесто пригодность и восприятие кода другими сотрудниками. Правило 17 - это самый настоящий anti-pattern программирования.
Плевать, что наш код вообще не работает, главное, чтобы порядок объявления функций совпадал с порядком определения этих функций! Да, вот так, господа...
Наверное разработчики Луны-25 придерживались этого правила.
Один из защитников этого требования сказал мне, что это требование нужно чтобы регулярно "отдыхать на работе от программирования" и просто двигать текст как кубики. Нормально так? Да?
18. Все комментарии должны начинаться с //~ и никак иначе!
Мы выдумаем свой фирменный стиль для однострочных комментариев. Так мы продвигаем свой бренд.
19. Запрет на многострочные комментарии /**/
20. Строжайший запрет на использование функций из <math.h> [sin() cos() log10() fabs() и т. п.] и <float.h>!
21. Рядом с глобальными переменными писать комментарием: "Смотрите, да это же глобальные переменные! О-го-го!".
Автор требований сказал, внимание..., что: "это красиво". Вот и в правду говорят, что "красота в глазах глядящего". Это же сколько надо выпить, чтобы такое красиво выглядело? Давайте тогда уж в каждый Си-файл вставлять изображение коровки в ASCI графике! Это же тоже красиво!
__.----.___
|| || (\(__)/)-'|| ;--` ||
_||____________||___`(QQ)'___||______;____||_
-||------------||----) (----||-----------||-
_||____________||___(o o)___||______;____||_
-||------------||----`--'----||-----------||-
|| || `|| ||| || || ||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^22. В верху си-файла писать название файла комментарием. Не важно, что это и так видно в файловой системе. А потом ещё следить, чтобы всегда совпадало. Везде...
23. В конце каждой функции писать комментарий: "смотрите, да это же конец функции! О-го-го!" А то ведь по фигурной скобке не ясно никому...
24. Все статические функции прописывать в конце файла. А потом ещё вверху второй раз прописывать прототипы этих функций.
При этом снова следить, чтобы порядок объявления static функций совпадал с порядком определения static функций.
Это просто анти патент, который буквально на пустом месте создают мышиную возню на целую неделю вперёд. Видимо, чтобы времени на работу больше потратить и увеличить вероятность рассинхронизировать имена переменных в прототипах и определениях.
Этого всего просто бы не пришлось делать, будь static функции определены в начале Си-файла.
Ничем не аргументированный стиль закрытия include guard
не так:
#endif // INCLUDE_FILE_H
а так:
#endif // #ifndef INCLUDE_FILE_HПисать одну страницу документации про каждую функцию в Cи-коде.
В конце каждого If писать комментарий: "смотрите да это же конец if(а) О-го-го". В конце каждого for писать комментарий: "смотрите это конец for О-го-го". В конце каждого switch писать комментарий: "смотрите это конец switch О-го-го". И тому подобное.
Запрет на запуск консольных утилит, которые были собраны локально.
Объявления функций должны в точности соответствовать их определениям
Перед началом каждой "секции" должно быть ровно три пустые строки
Описание функции должно начинаться с глагола, обозначающего что функция делает, в форме Present Simple в третьем лице
Ко всем константам для указания размера массива обязательно должен быть применен суффикс U. Пример: не Array[10] а Array[10U]
Правильно писать условия. Не if (Node), а if (NULL_PTR == Node). Чисто чтобы писанины было больше.
и тому подобное вплоть до номера 463....
Даже язык не поворачивается назвать такие порядки словом "инспекция программ". Это самая настоящая цензура.
Я вижу по меньшей мере три причины такого code-style.
1 Code-style как новая непонятная западная игрушка
Мы увидели в сериале "силиконовая долина", как там в компании "крысолов" делают инспекцию программ, как ругают сотрудников за пробелы и заставляют всех писать табы. Вот мы тоже тут решили так же делать. Ведь на западе люди живут хорошо . Если будем делать, как на западе, бишь тоже будем хорошо жить.
Требования к коду это хорошо, однако сами понимаете, что всё вышеперечисленное - просто требования ради требований. Больше похоже на цитаты туркменского президента, нежели на какой-то разумный стандарт разработки софтвера. Как говорят
Благими намерениями вымощена дорога в ад.
Думаю не надо пояснять, что такая мартыхина бюрократия лишь только тормозит достижение реального функционального результата по разработке system software. Как если бы отрыли тормозной парашют в самолёте на эшелоне.
При этом, добавлю, что в таких щепетильно "требовательных" организациях, как правило, не принято собирать проекты из скриптов, покрывать код модульными тестами, в прошивках нет NVRAM, в прошивках отсутствует UART-CLI для отладки функционала, нет и сервера сборки, никакого, даже в Jenkins, в прошивках нет загрузчика и многого того, что, по здравому смыслу вообще-то должно, быть как бы сделано как раз в первую очередь... Понимаете?...
Наш внутренний code-style - торжество формы над содержанием.
Порой всё это законотворчество выглядит, как соблюдать правила хирургической стерильности, в конюшне! Да.. Именно так... Не код, а Потёмкинская деревня какая-то.
Чрезмерные требования к оформлению кода похоже на какую-то армейскую IT-муштру.
У нас в организации инспекция программ - это торжество занудства.
Особенно смешно потом смотреть как эти же менеджеры компании на совещаниях слёзно жалуются, что якобы очень долго и медленно тянется разработка. Изменения вступают в силу только спустя месяц и более. А код ревьюверы, бедолаги, устают получать зарплату и покупать каждый год себе новые версии Apple iPhone за свою инспекцию программ.
2 Code-style как механизм увольнения толковых сотрудников
Обычно этот внутренний стандарт так составлен, что можно похерить абсолютно любой коммит. Причину можно придумать всегда, ибо надуманных правил просто немерено! Их сотни.
А утилиты авто-контроля, разумеется, специально нет в помине. Вот и появляется фактор субъективности... Не нравится коллега (более способный конкурент с хорошим опытом). Мучает черная зависть его мастерству... А-а-а-а. И давай hate(ить) его коммиты, пока тот не уволится.
Менеджер цензор в Gerrit(е) просто изгаляется над подчиненными программистами. Под предлогом нарушения внутреннего code-style всегда можно критиковать тех, кто "рожей не вышел". Красота!...
Cделай так, потому что я главный и всё!
Это ж ясно как день, так как у нас в организации есть например Си-код SPI драйвера, который прошел в репозиторий и при этом код написан с многочисленными нарушениями и патологиями нашего внутреннего код-стайла аж шестью программистами! Это как? Также есть нарушения код стайла в коде реализации uds протокола.
Одних можно гонять по IT-муштре, а других нельзя. Так что ли?
Как говорила классная руководительница в школе:
Власть без культуры - самая страшная вещь! Так как всегда приводит к порождению фашизма.
3 Code-style как забастовка по-итальянски.
Наш код стайл - это как забастовка по-итальянски. Делать код чрезмерно хорошо. Чтобы это заняло чрезмерное количество времени. До тех пор пока разработка уже будет абсолютно никому не нужна.
У нас есть плата на МК для перекладывание байт из CAN в UART. Не более того. Дак вот. Три человека для нее пишут прошивку уже 3 года и не видно ни конца ни края.
Cо стороны рядового менеджера, обильным количеством правил code style можно также полностью парализовать разработку нового софтвера во всей организации. Ну или, по крайней мере, отобрать ресурс для развития от чего-то более прогрессивного, такого как модульное тестирование, сборка из скриптов, диагностика функционала, автосборки и прочее. Раздувать code-style отличная стратегия для guerrilla-менеджера в стане противника.
У кого то на верху есть шкурный интерес, чтобы в России техника не развивалась. Любая. Вот они и внедряют сверху по разнорядке такой убийственный code-style оформления исходных кодов для микроконтроллеров. После которого ничего не растёт.
При этом угаре от code-style цензор игнорирует базовые фундаментальные принципы масштабируемости кода и предлагает даже прибивать гвоздями и hardcode(ить) функционал.
В таких организациях микроменеджеры настолько помешаны на код-стиле и на синтаксических понтах, что код может даже не собираться и при этом пройти инспекцию программ! Вот так... О корректном исполнении кода обычно там даже и речи не идет. Понимаете?..
Проблема в том, что как правило при приведении работающего кода к внутреннему стандарту внешнего вида работающий код, как правило, просто перестает работать. Понимаете?...
Если бы не наш внутренний code-style, мы бы давно уже были на Марсе! Вот так!
Правда в том, что каждое требование к коду сдвигает срок сдачи программного проекта на 10-15%. Когда в организации, например, 463+ правила оформления Си-кода, то время разработки, как ни крути, увеличивается в 46 раз! Понимаете?
Много комментариев это проблема
Когда у Вас в код-style много обязательных текстовых комментариев, то Вы на инспекции программ в Gerrit(е) фактически обсуждаете и делаете замечание не по коду, а по комментариям! В результате на код вообще никто не смотрит. А смысл code-reviw как раз в том, чтобы код улучшать.
При этом типичный российских цензон видит на 3-ей строчке первое попавшееся несоответствие по комментарию и сразу блочит весь коммит c 5k строк даже не глядя на остальной код. Сотрудник думает, что больше замечаний нет исправляет 3-ю строчку и выкатывает исправление этой 3-ей строчки. А цензор на следующий день блочит комит уже из-за неправильного комментария на 5-ой строчке и дальше не смотрит.
В результате принятие коммита в репозиторий затягивается на 3-6 месяцев. Вот такие вот пирожки с капустой. Понимаете?...
Скажите мне, смог бы солдат Курчатов Игорь Васильевич сделать плутониевую бомбу с нуля за 4 года с такой вот мартыхиной бюрократией? Уверен что ответ Вам и так всем понятен...
4. Code-style как механизм раздувания бюджета на разработку
Какие достоинства у внутреннего сode-style?
Я лично абсолютно ничего не имею против списка требований к коду. Как говорят:
Любой каприз за Ваш счёт...
Это даже здорово, что есть стабильная предсказуемая работа вокруг всего этого цирка.
На самом деле это даже здорово придумывать всё новые и новые требования к code style. Так менеджер может аргументировать владельцам бизнеса раздувание фронта работ, что тебе и коллегам гарантирована оплачиваемая работа на обозримую перспективу. Можно годами как пиявка высасывать из частной компании зарплату за то, что с меньшими требованиями к code style можно сделать максимум за 2-3 месяца.
Аж дух захватывает от того сколько времени и денег можно распилить на разработке ПО с абсурдным code-style-ом. Надо добавить больше правил code-style-ла !!!. До бесконечности, настолько много правил code-style насколько это только возможно!!!
Итоги
Вот объясните мне, пожалуйста, в самом деле, в чем глубинный подлинный смысл упомянутых тут выше требований к коду?
Было бы нормально, если эти требования сопровождались бы короткой, ясной и прозрачной аргументацией для чего их так рьяно нагнетают. И чтобы были выставлены приоритеты какие требования более важные, а какие желательны, как в MISRA.
Требований можно выдумывать сколько душе удобно, но тогда должен быть либо:
1--Консольная tool(a) для автоматической установки таких требований: а-ля clang-format
2--Консольная tool(a) для автоматического поиска и выявления нарушений требований: а-ля cpp-check
Однако наши цензоры не способны написать такие утилиты-локаторы. Им для этого квалификации не хватает. Они могут code-style только придумывать.
----
Пишите в комментариях какие странные требования к оформлению исходников есть или были в вашей организации. Мне просто интересно можно ли придумать что-то ещё более абсурдное в разработке на Си, чем то, что я перечислил в этой заметке.
Ссылки
