Пирамида инспекции кода

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

Недавно я разместил в своем Твиттере небольшую иллюстрацию, которая проливает свет на эту проблему и дает наводку, на каких аспектах следует сосредоточиться прежде всего, и назвал ее «Пирамида инспекции кода». Ее назначение – помочь держать в приоритете составляющие инспекции кода, имеющие первостепенную важность (по крайней мере, на мой взгляд), а так же указать, какие составляющие можно и нужно автоматизировать.

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

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

Ярусы перечисляются от верхнего к нижнему.

Стиль

Какие вопросы задавать:

• Применяется ли принятый для проекта стиль форматирования?
• Соблюдаются ли договоренности относительно названий?
• Следует ли код принципу DRY (Don’t Repeat Yourself – Не повторяйтесь)?
• Достаточно ли «читабелен» код (с точки зрения длины методов и так далее)?

Тесты

Какие вопросы задавать:

• Благополучно ли пройдены все тесты?
• В достаточной ли степени протестирована новая функциональность?
• Протестированы ли граничные случаи?
• Применяется ли модульное тестирование по возможности и интеграционное тестирование при необходимости?
• Представлено ли нефункциональное тестирование (например, производительности)?

Документация

Какие вопросы задавать:

• Достаточно ли документации для новой функциональности?
• Все ли актуальные документы представлены (README, API-документация, руководство пользователя, справочная документация и так далее)?
• Все ли документы доступны для понимания – без опечаток и серьезных грамматических ошибок?

Семантика имплементации

Какие вопросы задавать:

• Соответствует ли семантика исходным требованиям?
• Нет ли ошибок в логике?
• Нет ли переусложненности?
• Как обстоят дела с надежностью (нет ли проблем с конкурентностью, налажена ли должным образом обработка ошибок)?
• Как обстоят дела с производительностью?
• Как обстоят дела с безопасностью (в плане внедрения SQL-кода и других проблем)?
• Как обстоят дела с отслеживанием (например, метрики, логирование, трассировка)?
• Выполняют ли свежедобавленные зависимости свою работу? Всё ли у них в порядке с лицензиями?

Семантика API

Какие вопросы задавать:

• Размер API достаточен и в то же время не избыточен?
• Каждая операция выполняется одним способом, а не несколькими?
• Выдерживается ли согласованность и принцип «минимум сюрпризов»?
• Четко ли разделены внутренний и внешний API, не подтекает ли внутренний во внешний?
• Нет ли каких-то изменений, вызывающих неисправности в частях приложения, обращенных к пользователю (классы API, конфигурация, форматы логов и так далее)?
• Можно ли в целом назвать API полезным и не слишком узконаправленным?

FAQ

А почему пирамида?

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

Так это же треугольник!

Вам так только кажется. Это пирамида, вид сбоку.

Какими инструментами ты пользовался, когда создавал это изображение?

Excalidraw.