Пролог
В некоторых организациях, в которых программируют микроконтроллеры есть свой внутренний стандарт оформления Си-исходников (сорцов). Как правило там обычно есть разумные пункты. Однако в этом тексте я перечислил самые нелепые и абсурдные требования и рекомендации оформления сорцов, которые реально присутствуют в современных российских электронных организациях, где программируют микроконтроллеры.
Это требования категории, мягко говоря, "зачем?". Вот буквально несколько реальных примеров из жизни. Это просто диктатура абсурда, парад нелепости.
1. Запрет установки программ, запрет открытия диспетчера устройств, запрет открытия диспетчера задач, запрет прописывания переменной PATH на локальных PC. Всё только через пароль руководителя отдела.
2. Собирать код только мышкой из-под GUI-IDE (IAR или KEIL) и никаких там скриптов сборки (Make, CMake)! У нас зарплатный фонд такой, что мы можем нанять только студентов, а они умеют программировать только в IDE. Мышкой.
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. Кто-то как будто специально выдумал это аутистское форматирование кода в столбик, чтобы саботировать разработку ПО во всей организации. Другого объяснения, тут придумать, простите, но просто нереально....
16. Для всех объявлений глобальных функций в h-файле обязательно ключевое слово extern! Не важно, что и без extern код собирается и работает.
17. Порядок объявления функций должен совпадать с порядком определения функций. Просто лишнее правило, чтобы время больше потратить.
18. Все комментарии должны начинаться с //~ и никак иначе!
Мы выдумаем свой фирменный стиль для однострочных комментариев. Так мы продвигаем свой бренд.
19. Запрет на многострочные комментарии /**/
20. Строжайший запрет на использование функций из <math.h> [sin() cos() log10() fabs() и т. п.]!
21. Рядом с глобальными переменными писать комментарием: "Смотрите, это глобальные переменные!"
22. В верху си-файла писать название файла комментарием. Не важно, что это и так видно в файловой системе. А потом еще следить, чтобы всегда совпадало. Везде.
23. В конце каждой функции писать комментарий: "смотрите, это конец функции!" А то ведь по фигурной скобке не ясно...
24. Все статические функции прописывать в конце файла. А потом ещё вверху второй раз прописывать прототипы этих функций. Видимо, чтобы времени на работу больше потратить и увеличить вероятность рассинхронизировать имена переменных в прототипах и определениях.
Ничем не аргументированный стиль закрытия include guard
делать закрытие include guard не так:
#endif // INCLUDE_FILE_H
а вот эдак:
#endif // #ifndef INCLUDE_FILE_HВ конце каждого If писать комментарий: "смотрите это конец if". В конце каждого for писать комментарий: "смотрите это конец for". В конце каждого switch писать комментарий: "смотрите это конец switch". И тому подобное.
Запрет на использование оператора switch. Вместо этого делать лесенку из if() {}else if(){}....
Запрет на запуск консольных утилит, которые были собраны локально.
Требования к коду это хорошо, однако сами понимаете, что всё вышеперечисленное - просто требования ради требований. Больше похоже на цитаты туркменского президента, нежели на какой-то разумный стандарт разработки софтвера. Как говорят
Благими намерениями вымощена дорога в ад.
Думаю не надо пояснять, что такая мартышкина бюрократия лишь только тормозит достижение реального функционального результата по разработке system software. Как если бы отрыли тормозной парашют в самолёте на эшелоне.
При этом, добавлю, что в таких щепетильно "требовательных" организациях, как правило, не принято собирать проекты из скриптов, покрывать код модульными тестами, в прошивках нет NVRAM, в прошивках отсутствует UART-CLI для отладки функционала, нет и сервера сборки, никакого, даже в Jenkins, в прошивках нет загрузчика и многого того, что, по здравому смыслу вообще-то должно, быть сделано как раз в первую очередь... Понимаете?...
Порой всё это законотворчество выглядит, как соблюдать правила хирургической стерильности, в конюшне! Да.. Именно так... Чрезмерные требования к оформлению кода похоже на какую-то армейскую IT-муштру.
Итоги
Вот объясните мне, пожалуйста, в чем глубинный смысл упомянутых выше требований к коду?
Было бы нормально, если эти требования сопровождались бы короткой, ясной и прозрачной аргументацией для чего их так рьяно нагнетают. И чтобы были выставлены приоритеты какие требования более важные, а какие так...
Я лично абсолютно ничего не имею против списка требований к коду. Это даже здорово, что есть стабильная предсказуемая работа вокруг всего этого цирка.
На самом деле это даже здорово придумывать всё новые и новые требования к code style. Так можно аргументировать раздувание фронта работ начальству, что тебе и коллегам гарантирована оплачиваемая работа на обозримую перспективу. Можно годами как пиявка высасывать из компании зарплату за то, что с меньшими требованиями к code style можно сделать максимум за 2-3 месяца.
Я к тому, что требований можно выдумывать сколько душе удобно, но тогда должен быть либо:
1--консольная tool(a) для автоматической установки таких требований: а-ля clang-format
2--консольная tool(a) для автоматического поиска и выявления нарушений требований: а-ля cpp-check
Правда в том, что каждое требование к коду сдвигает срок сдачи программного проекта на 10-15%. Когда в организации, например, 463+ правила оформления Си-кода, то время разработки, как ни крути, увеличивается в 46 раз! Понимаете?
Как говорят:
Любой каприз за Ваш счёт...
Скажите мне, смог бы солдат Курчатов Игорь Васильевич сделать атомную бомбу с нуля за 4 года с такой вот мартыхиной бюрократией? Думаю ответ и так всем понятен...
Пишите в комментариях какие странные требования к оформлению исходников есть или были в вашей организации. Мне просто интересно можно ли придумать что-то ещё более абсурдное в разработке на Си, чем то, что я перечислил в этой заметке.
Ссылки
