Стандарт оформления кода
Набор правил и соглашений, используемых при написании исходного кода на некотором языке программирования.
Назначение документа — повышение эффективности разработчиков за счёт облегчения восприятия кода и снижения количества ошибок.
Хороший стандарт оформления кода должен учитывать:
какие действия с кодом чаще всего выполняют программисты;
какие факторы могут мешать выполнять эти действия или способствовать появлению ошибок.
Давайте разберём распространённые случаи.
Как программисты работают с кодом
Чтение кода
Программисты постоянно читают код. И здесь для программиста самое важное — правильно и быстро понять написанное. Как сказал Мартин Фаулер:
Любой дурак может написать код, понятный компьютеру. Хороший программист пишет код, понятный человеку.
Какие проблемы у программиста могут возникнуть при чтении кода?
Заумный код
Некоторые программисты любят использовать «красивые» конструкции, которые часто непонятны с первого взгляда.
Сравните два фрагмента, делающих одно и то же.
a < b ? console.log('true') | alert('Hi!') : console.log('false')
if (a < b) {
console.log('true')
alert('Hi!')
} else {
console.log('false')
}
Согласитесь, что понять второй вариант проще и взглядом он считывается мгновенно, тогда как первый вариант заставляет задуматься и потратить несколько секунд на понимание.
К чему это приводит? Программисты, читающие такой код, тратят больше времени на понимание логики. При изменении такого кода возрастает риск ошибок из-за неправильного его понимания.
Хороший стандарт оформления кода должен запрещать подобные конструкции в пользу, может и бо́льших по объёму, но более понятных.
Чрезмерная краткость
Некоторые программисты считают, что чем меньше кода, тем лучше. В целом это верно, но не стоит впадать в крайности: стремление к краткости не должно идти в ущерб понятности и лёгкости чтения кода.
План
Привести пример чрезмерной краткости в коде.
Хороший стандарт оформления кода должен ограничивать увлечение крайностями и стремиться к балансу между краткостью и понятностью.
Неряшливый код
План
Привести пример «неряшливого» кода.
Плохо структурированный, небрежно оформленный код мешает восприятию сразу по двум причинам.
Люди в принципе легче воспринимают структурированный текст, подчиняющийся некоторым закономерностям.
Неряшливый код вызывает психологическое неприятие из-за которого вполне верный код может неосознанно восприниматься читателем как неправильный.
Хороший стандарт оформления кода должен делать код опрятным и лёгким для восприятия.
Разный стиль
Люди плохо воспринимают непривычное. Когда разработчик видит непривычно оформленный код, то основное внимание он уделяет его форме, а не содержанию. А недостаточное внимание к содержанию может привести к возникновению ошибок.
Если оформление очень уж сильно отличается от привычного, это может вызывать раздражение и предубеждение к такому коду или даже к его автору. Увы, наш мозг так устроен, что «некрасивый» код может начать воспринимать как «неправильный». Иногда раздражение может перекидываться и на самого автора кода, что может заставить нас подсознательно воспринимать все его решения как «плохие» или «неправильные».
Хороший стандарт оформления кода должен стремиться к единообразию.
Поиск в коде
Поиск в чужом коде — одно из самых частых действий с кодом. При этом программист не читает код, а бегло просматривает. Крайне важно понимать, что он ищет код, соответствующий его ожиданиям. Это напоминает поиск по регулярному выражению — человек «составляет» в уме некий шаблон того, что он ожидает найти, далее он просматривает текст на соответствие этому шаблону. При этом наш мозг так устроен, что скорее всего он «не увидит» то, что шаблону не соответствует.
Хороший стандарт оформления кода должен стремиться упростить поиск по коду.
Слияние версий кода
Тоже довольно частое действие. Если при слиянии двух веток образуются конфликты, то программисту приходится разрешать их вручную. При этом имеется риск ошибиться и получить нерабочий код.
Хороший стандарт оформления кода должен стараться снизить такой риск.
Статический анализ кода
Статический анализ кода — мощное средство повышения качества и эффективности, без которого сложно представить современную разработку ПО. Однако инструменты статического анализа имеют один существенный недостаток — они не умеют догадываться о том, что не отражено в коде явно. Соответственно «магические» конструкции или неформальные договорённости могут мешать качественному анализу.
Подробнее см. Статический анализ кода.
Хороший стандарт оформления кода должен способствовать использованию статического анализа.
Порог вхождения для новых разработчиков
Если проект живёт достаточно долго, то к нему обязательно будут подключаться новые разработчики. И чем быстрее они смогут понять код проекта, тем раньше они начнут работать в полную силу и приносить проекту пользу.
Хороший стандарт оформления должен быть максимально привычен и понятен максимальному кругу программистов.
Шаблон стандарта оформления кода
Описанное в этом разделе — лишь примерный шаблон стандарта. Обязательно учитывайте ваши условия: особенности проекта, команды, используемых языков и т. п.
Примечание
Ключевые слова НЕОБХОДИМО (ТРЕБУЕТСЯ, НУЖНО, ДОЛЖНО БЫТЬ), НЕДОПУСТИМО (НЕ ПОЗВОЛЯЕТСЯ), СЛЕДУЕТ (РЕКОМЕНДУЕТСЯ), НЕ СЛЕДУЕТ (НЕ РЕКОМЕНДУЕТСЯ), ВОЗМОЖНО, НЕОБЯЗАТЕЛЬНО в данном разделе должны интерпретироваться в соответствии с требованиями RFC 2119.
1. Общие принципы оформления кода
1.1. НЕОБХОДИМО оформлять код так, чтобы:
1.2. В случае противоречий между целями из п. 1.1 НЕОБХОДИМО отдавать предпочтение цели, расположенной выше в списке. Однако при этом также НЕОБХОДИМО учитывать значимость и вероятность устраняемых проблем. Примеры:
запись облегчающая понимание, но усложняющая слияние версий допустима;
запись усложняющая понимание, но упрощающая слияние версий недопустима;
запись не сильно облегчающая понимание, но сильно усложняющая слияние версий нежелательна.
Приоритеты
Ошибки
Слияние
Единообразие
Наглядность, ясность.
Статический анализ.
Следование сложившимся традициям