понедельник, марта 17, 2008

Code conventions

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

2 комментария:

Анонимный комментирует...

по-моему, бред...даже насчет ограничения документа 4мя листами ... посмотрите хотя бы на тот же самый гайд от ms по .net

///
да и говорить об ограничении документа каким-то количеством бумаги тоже бред, если соглашение по оформлению кода толковое, и принятое на уровне команды, то и читаться, восприниматься оно будет влет

насчет необходимости такого документа как соглашение о правилах оформления кода даже спорить на мой взгляд не стоит, в любом монастыре должен и есть свой устав, если ктото не согласен, есть линейка по пальцам в виде проведение такого мероприятия как codereview

удачи

Miroff комментирует...

Гайд M$ расчитан на несколько языков. И то он не слишком популярен в среде дотнетчиков.

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

Второй смысл: чем сложнее процедура, тем труднее добиться ее соблюдения. В данном случае обширный документ требует обязательного регулярного дорогого code review. Малейшее послабление, например, в результате аврала, скорее всего приведет к тому, что конвенциями будет пожертвовано. В то время как простое и понятное соглашение скорее всего будет соблюдаться, особенно если оно подкреплено автоматическими средствами.