[Перевод] Пирамида инспекции кода
При инспекции кода часто складывается такая ситуация: какие-то обыденные моменты вроде форматирования или стиля рассматриваются очень тщательно, вокруг них ведутся бесконечные обсуждения, в то время как важным аспектам (выполняет ли код те функции, на которые рассчитан, производителен ли он, есть ли у него обратная совместимость с существующими клиентами и многое другое) уделяется гораздо меньше внимания.
Недавно я разместил в своем Твиттере небольшую иллюстрацию, которая проливает свет на эту проблему и дает наводку, на каких аспектах следует сосредоточиться прежде всего, и назвал ее «Пирамида инспекции кода». Ее назначение — помочь держать в приоритете составляющие инспекции кода, имеющие первостепенную важность (по крайней мере, на мой взгляд), а так же указать, какие составляющие можно и нужно автоматизировать.
Некоторые читатели попросили дать альтернативную, постоянную ссылку, которой можно делиться; другие хотели получить картинку в высоком разрешении. Поэтому я выкладываю ее повторно, на своем сайте. Вы можете также скачать изображение в формате SVG.
В нижней части располагаются аспекты, которые сложнее будет корректировать в будущем, в верхней части — те, которые корректировать будет проще. Сосредоточить усилия лучше на трех нижних ярусах. Два верхних яруса подходят для автоматизации.
Ярусы перечисляются от верхнего к нижнему.
Стиль
Какие вопросы задавать:
- Применяется ли принятый для проекта стиль форматирования?
- Соблюдаются ли договоренности относительно названий?
- Следует ли код принципу DRY (Don«t Repeat Yourself — Не повторяйтесь)?
- Достаточно ли «читабелен» код (с точки зрения длины методов и так далее)?
Тесты
Какие вопросы задавать:
- Благополучно ли пройдены все тесты?
- В достаточной ли степени протестирована новая функциональность?
- Протестированы ли граничные случаи?
- Применяется ли модульное тестирование по возможности и интеграционное тестирование при необходимости?
- Представлено ли нефункциональное тестирование (например, производительности)?
Документация
Какие вопросы задавать:
- Достаточно ли документации для новой функциональности?
- Все ли актуальные документы представлены (README, API-документация, руководство пользователя, справочная документация и так далее)?
- Все ли документы доступны для понимания — без опечаток и серьезных грамматических ошибок?
Семантика имплементации
Какие вопросы задавать:
- Соответствует ли семантика исходным требованиям?
- Нет ли ошибок в логике?
- Нет ли переусложненности?
- Как обстоят дела с надежностью (нет ли проблем с конкурентностью, налажена ли должным образом обработка ошибок)?
- Как обстоят дела с производительностью?
- Как обстоят дела с безопасностью (в плане внедрения SQL-кода и других проблем)?
- Как обстоят дела с отслеживанием (например, метрики, логирование, трассировка)?
- Выполняют ли свежедобавленные зависимости свою работу? Всё ли у них в порядке с лицензиями?
Семантика API
Какие вопросы задавать:
- Размер API достаточен и в то же время не избыточен?
- Каждая операция выполняется одним способом, а не несколькими?
- Выдерживается ли согласованность и принцип «минимум сюрпризов»?
- Четко ли разделены внутренний и внешний API, не подтекает ли внутренний во внешний?
- Нет ли каких-то изменений, вызывающих неисправности в частях приложения, обращенных к пользователю (классы API, конфигурация, форматы логов и так далее)?
- Можно ли в целом назвать API полезным и не слишком узконаправленным?
FAQ
А почему пирамида?
Нижние ярусы должны составлять основу инспекции кода и занимать большую часть потраченного на нее времени.
Так это же треугольник!
Вам так только кажется. Это пирамида, вид сбоку.
Какими инструментами ты пользовался, когда создавал это изображение?
Excalidraw.
