Code conventions
Через пару недель проекта, особенно если оный был расчитан на достаточно долгий срок, всегда находится гаврик, считающий, что для успешного существования проекта необходимо немедленно, пока не слишком поздно, написать code conventions. Не будучи вовремя остановленным, он за один присест порождает страниц, эдак, двадцать, заполненных беспорядочными правилами, вроде:
Имена переменных должны удовлетворять camelCase;
Недопустимо обращение через две точки, во имя закона Деметры;
Бинарные операторы должны быть отделены пробелами с обоих сторон;
В сеттерах нужно использовать this;
Забытая в микроволновке еда считается общей;
и т.д.
Обычно такой документ живет ровно две недели, затем перемещается в архив, извлекаемый оттуда только для того чтобы продемонстрировать его новичкам. Поскольку документ изначально не соблюдался и разительно отличается от негласных соглашений принятых в коде, новички тоже откладывают его в сторону. От проекта к проекту такая ситуация повторяется с завидной регулярностью. Причина в том, что любая дополнительная активность, как написание комментариев, проверка кода на соответствие соглашениям, комментарии к коммиту в VCS требует дополнительных затрат. Если преимущества от этих действий неочевидны человек склонен «забывать» их делать. Поэтому введение в проекте code conventions автоматически означает появление роли следящего за их соблюдением. Для того чтобы решить проблему недостаточно опубликовать документ, каким бы хорошим он ни был. Нужна постоянная активность, это везде так. Отлично, но следить за соблюдением правил, описанных на двадцати страницах, отнимает прорву времени. И это вторая причина, по которой затея с code conventions проваливается.
Теперь, когда мы добрались до сути, мы можем сформулировать рекомендации для написания соглашений. Но, сперва, давайте обозначим проблему, которую мы собираемся решать. Разные программисты предпочитают разные стили написания кода. Если несколько разных стилей смешиваются в одном файле, этот файл становится трудным для чтения. Разнобой в стиле выглядит неряшливо и поощряет неряшливость уже в самом коде. Соглашения о коде призваны устранять неоднозначности в выборе несущественных деталей оформления, в идеале сужая пространство вариантов до одного. Как же писать code conventions?
Определите кто ваши программисты. Кто сказал: «Они все здесь»? А как же библиотеки, которыми вы пользуетесь. Их интерфейсы должны вашим соглашениям. Естественно, вы не в силах заставить сторонних разработчиков соблюдать ваши стандарты, но вы всегда можете подогнать стандарты под них. В противном случае использование библиотек будет выбиваться из общего стиля и увеличивать энтропию проекта.
Все соглашения можно разделить на две части: поддающиеся автоматическому переформатированию и не поддающиеся. Переформатированию поддаются такие вещи как количество пробелов, формирование отступов, расположение скобок, длина строк
и т.п.
Лучший способ их публикации, это положить в VCS файл настроек для IDE. Можно также настроить VCS сервер на вызов автоформаттера перед каждым коммитом и забыть о них навсегда. Описывать их в документе совершенно не обязательно. Не стоит поручать человеку делать то, что сумеет машина. Не поддаются переформатированию такие вещи, как имена файлов, переменных, пакетов и классов, стиль работы с исключениями, расположение файлов. Продвинутые автоформаттеры умеют отлавливать ошибки, но исправлять из автоматически невозможно. Поэтому все что не поддается автоформатированию придется описать в документе явно.
Документ содержащий code conventions не должен быть большим. Четырех страниц более чем достаточно. По крайней мере ограничение объема избавит вас от соблазна включать в документ правила пользования микроволновкой.
Если есть возможность, не изобретайте велосипедов. Почти всегда можно взять готовые документы у разработчиков языка или людей в нем авторитетных. Вот несколько таких примеров:
Утилиты для автоформатирования кода:
