Теперь перейдём к артефактам реализации требований девятого процесса ГОСТ Р 56939-2024:
5.9.3.1 Регламент проведения экспертизы исходного кода ПО должен содержать следующие сведения:
- обязанности сотрудников и их роли при проведении экспертизы исходного кода ПО;
- базовые требования к экспертизе (количество участников; области кода, подлежащего экспертизе; используемые инструменты и т. д.);
- описание основных проверок (например, сценариев, шаблонов, чек-листов) проведения экспертизы исходного кода ПО.
Думаю, суть описана достаточно и понятно. Конкретика уже зависит от ваших нужд, предпочтений, возможностей, типа проекта и т.д. Если хочется от чего-то оттолкнуться, то уже в который раз рекомендую книгу Стива Макконнелла "Совершенный код" ("Code Complete", Steve McConnell). В ней очень много и хорошо написано про обзоры кода.
Проводя обзор кода, важно не забывать про такие высокоуровневые задачи, как:
- обучение членов команды, передача опыта и знаний о проекте новым сотрудникам;
- поиск высокоуровневых ошибок, недостатков выбранных архитектурных решений, неэффективных/опасных подходов в реализации.
Это я вот к чему. Есть риск увлечься на обзорах вопросами оформления кода и поиском опечаток. Это, конечно, тоже полезно и является частью процесса обзоров. Однако часть опечаток помогут найти статические анализаторы кода. Тем более что некоторые опечатки человеку сложно заметить. Вопросы оформления помогают решить правила кодирования (см. предыдущий восьмой процесс) и утилиты автоформатирования. А вот обучение, передача опыта, обсуждение алгоритмов и выявление высокоуровневых недостатков в безопасности и в целом — это всё остаётся только на людях. Полезно не забывать про всё это во время обзора кода.
5.9.3.2 Результаты экспертизы кода должны содержать следующие сведения:
- информацию о проанализированных модулях (компонентах) ПО;
- перечень необходимых изменений;
- вопросы к частям кода, экспертиза которых затруднена и требует дополнительных разъяснений;
- предложения по улучшению.
Здесь, думаю, программистам всё тоже понятно. Остановлюсь только на пункте "вопросы к частям кода, экспертиза которых затруднена и требует дополнительных разъяснений".
Считается, что на обзорах кода тот, кто написал код, не может давать разъяснения, как он работает. Если код непонятен коллегам, значит его надо переписать или снабдить комментариями. Код должен стать самодостаточным для понимания.
Полностью поддерживаю эту идею. На практике, конечно, это тяжело воплотить. Слишком жёсткий подход будет затягивать цикл обзоров фрагмента кода и делать этот процесс в целом очень медленным и трудозатратным. А иногда надо просто что-то быстро сделать, а не заниматься созданием некого идеального кода :) Так что везде нужен баланс. Однако идея хорошая, и по возможности стоит приближаться к её воплощению в реальности :)
P.S. Про написание комментариев. Комментарии должны отвечать не на вопрос "что делаем?", а на вопрос "зачем/почему делаем?". Подробнее — в главе N53 "60 антипаттернов для С++ программиста".