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

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

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

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

q0yl3luj_67iddk3hnp83n_uowe.png


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

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

Стиль


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

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


Тесты


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

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


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


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

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


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


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

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


Семантика API


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

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


FAQ


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

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

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

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

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

Excalidraw.

© Habrahabr.ru