Топ 8 правил, чтобы ваш код читали
Код читают в десятки раз чаще, чем пишут, — и чаще всего его читаете вы сами через полгода. Восемь правил, которые делают чтение возможным, без споров о табах и скобках.
Для кого вы пишете
Главный читатель вашего кода — не коллега и не ревьюер, а вы сами через шесть месяцев, когда контекста в голове уже не останется. Всё остальное следует из этого.
Что не входит в понятие читаемости. Отступы, кавычки и расстановка скобок. Об этом не спорят — это настраивается автоформатированием один раз и снимается с повестки навсегда. Читаемость — про имена, размер, структуру и объяснение решений.
Топ 8 правил
Имена, которые не нужно расшифровывать
самое дешёвое улучшение из возможных
Переменная d экономит вам три секунды при наборе и стоит читателю минуты на выяснение, что это за d. Имена data, temp, result, handle не лучше: они не говорят ничего.
Практический критерий. По имени должно быть понятно, что внутри и в каких единицах. timeoutSeconds лучше, чем timeout: второе оставляет вопрос про миллисекунды, а на этом вопросе регулярно ломаются интеграции.
Про длину. Длинное точное имя лучше короткого непонятного. Исключение — счётчик цикла на три строки: там i читается нормально, потому что контекст виден целиком.
- Убирает большую часть необходимости в комментариях
- Ничего не стоит и не требует договорённостей
- Современные редакторы дописывают за вас
- Переименование в старом коде требует аккуратности
- Хорошее имя иногда приходится подбирать долго
всегда · оценка 9,6
Функция помещается на экран
правило грубое, но работает лучше тонких
Если функцию приходится прокручивать, вы уже не видите её целиком и не удержите в голове. Точное число строк не важно — важно, что вся логика видна одновременно.
Признак, что пора делить. В описании функции появляется союз «и»: «проверяет права и сохраняет заказ и отправляет письмо». Это три функции, а не одна.
Обратная крайность. Дробить на функции по три строки, вызывающие друг друга цепочкой, — тоже плохо: чтобы понять простое действие, приходится прыгать по пяти файлам. Здравый смысл важнее правила.
- Логика видна целиком без прокрутки
- Короткие функции легче тестировать
- Легко заметить, что функция делает лишнее
- Слишком мелкое дробление ухудшает читаемость
- Формальное следование правилу порождает бессмысленные обёртки
почти всегда · оценка 9,3
Комментарии про «зачем», а не про «что»
и первое действительно нужно
Комментарий, пересказывающий код, — мусор: он устаревает при первой правке и врёт. Комментарий, объясняющий решение, бесценен, потому что этой информации в коде нет и взять её негде.
Что стоит объяснять. Почему выбран именно такой подход, какой очевидный вариант не сработал и почему, откуда взялось странное число, какой внешний сервис ведёт себя не по документации.
Хороший ориентир. Если во время написания вы подумали «тут не всё очевидно» — напишите одну строку про это. Именно на такие места читатель потом тратит часы.
- Сохраняет знание, которого нет в коде
- Экономит часы будущим читателям
- Помогает не переделать обратно то, что уже пробовали
- Устаревшие комментарии хуже отсутствующих
- Соблазн комментировать очевидное
по необходимости · оценка 9,2
Ранний выход вместо лестницы вложенности
убирает самый утомительный вид кода
Пять уровней вложенных условий заставляют держать в голове весь путь. Проверьте исключительные случаи в начале и выйдите из функции — основная логика останется на первом уровне.
Как это выглядит. Вместо «если пользователь есть, то если у него доступ, то если заказ существует, то сделать» — три отдельные проверки с немедленным выходом, а потом одно понятное действие.
Побочный эффект. Такой код гораздо проще менять: новое условие добавляется отдельной строкой, а не втискивается в середину лестницы.
- Основная логика не тонет в отступах
- Проверки видны сразу и в одном месте
- Новые условия добавляются без перестройки
- Много точек выхода не всем нравится стилистически
- В языках без исключений требует аккуратности с очисткой ресурсов
всегда · оценка 9,1
Один коммит — одно изменение
читаемость истории не менее важна, чем читаемость файлов
Коммит, в котором одновременно исправлена ошибка, переименованы файлы и переформатирован модуль, невозможно ни отревьюить, ни откатить. Разделяйте: сначала переформатирование, отдельно — исправление.
Сообщение коммита. Отвечает на «зачем», а не на «что»: «поправил» — бесполезно, «убрал повторный запрос при обновлении списка» — полезно. Через год именно по этим строкам вы будете искать причину.
Инструмент. Добавление изменений по частям позволяет разложить накопившуюся кашу правок на осмысленные коммиты. Подробнее — в разборе того, что нужно знать про Git.
- Историю можно читать и понимать
- Ошибочное изменение легко откатить точечно
- Ревью проходит быстрее и качественнее
- Требует дисциплины в момент, когда хочется просто закоммитить всё
- Разделение задним числом занимает время
каждый день · оценка 9,0
Ошибки, по которым понятно, что делать
сообщение об ошибке — тоже интерфейс
«Что-то пошло не так» и молчаливое проглатывание исключения — два способа гарантировать, что причину будут искать полдня. В сообщение нужно класть контекст: что делали, с какими данными, что именно не получилось.
Правило про проглатывание. Пустой перехват исключения без записи в лог — почти всегда ошибка. Если исключение действительно можно игнорировать, напишите комментарием, почему.
Что не должно попадать в сообщения. Пароли, ключи и персональные данные: логи читают больше людей, чем кажется, и хранятся они дольше, чем нужно.
- Резко сокращает время поиска причины
- Помогает и пользователю, и разработчику
- Ничего не стоит в момент написания
- Легко случайно записать в лог лишнее
- Слишком подробные логи мешают искать в них нужное
всегда · оценка 8,9
Никаких «магических» значений
число 86400 посреди кода — загадка на будущее
Число или строка без объяснения в середине выражения заставляет гадать. Вынесенная константа с внятным именем снимает вопрос и заодно позволяет поменять значение в одном месте.
Особенно важно для повторяющихся значений. Одно и то же число в пяти местах — гарантия, что однажды поменяют в четырёх.
Где не нужно. Ноль, единица и очевидные в контексте значения в константы выносить не надо — это создаёт лишний слой без пользы.
- Смысл значения виден сразу
- Меняется в одном месте
- Проще искать по проекту
- Избыточное вынесение засоряет код
- Плохое имя константы не лучше самого числа
почти всегда · оценка 8,8
Автоформатирование и проверки в репозитории
снимает целый класс споров навсегда
Настроенный форматировщик и статический анализатор, запускающиеся автоматически, убирают из ревью все замечания про пробелы и стиль. Остаётся только то, ради чего ревью и делается: логика и решения.
Как внедрять. Один коммит, который форматирует весь проект разом, — и дальше правило соблюдается само. Постепенное внедрение не работает: половина файлов остаётся в старом виде на годы.
Важная деталь. Тот самый форматирующий коммит стоит пометить, чтобы он не мешал читать историю строк: иначе окажется, что весь файл «написан» в день переформатирования.
- Споры о стиле прекращаются
- Ревью занимается смыслом, а не запятыми
- Настраивается один раз
- Большой коммит с переформатированием мешает истории
- Слишком строгие проверки начинают мешать работе
разово · оценка 8,7
Сравнение по главному
| Правило | Усилие | Эффект | Когда применять |
|---|---|---|---|
| Хорошие имена | минимальное | очень высокий | всегда |
| Короткие функции | среднее | высокий | почти всегда |
| Комментарии «зачем» | минимальное | высокий | по необходимости |
| Ранний выход | минимальное | высокий | всегда |
| Атомарные коммиты | среднее | высокий | каждый день |
| Внятные ошибки | минимальное | высокий | всегда |
| Именованные константы | минимальное | средний | почти всегда |
| Автоформатирование | разовое | средний | один раз |
Как это внедрить в команде
Начните с инструментов, а не с правил. Форматировщик и анализатор в репозитории решают половину вопросов без единого разговора.
Договоритесь о трёх правилах, а не о тридцати. Документ на сорок страниц не читает никто. Три пункта, которые все помнят, работают лучше.
В ревью обсуждайте решения, а не вкусы. «Мне не нравится» — не аргумент. «Здесь при пустом списке будет ошибка» — аргумент.
Правило бойскаута. Тронули файл — оставьте его чуть лучше, чем нашли: одно имя, один комментарий. Отдельные проекты «наведём порядок во всём» почти никогда не доживают до конца.
Частые вопросы
Нужны ли комментарии, если код и так понятный?
Комментарии про «что делает код» — не нужны, их заменяют хорошие имена. Комментарии про «почему сделано именно так» нужны всегда, потому что этой информации в коде физически нет. Проверка простая: если удалить комментарий и ничего не потеряется — он был лишним.
Что делать со старым проектом, где всё плохо?
Не переписывать целиком — такие проекты почти всегда проваливаются. Работает другое: настроить автоформатирование одним коммитом и дальше улучшать только те файлы, которые вы и так трогаете по задачам. За год код становится заметно лучше, и это не стоит отдельного бюджета.
А если код пишет ИИ-помощник?
Правила те же, только внимательности нужно больше: сгенерированный код выглядит аккуратно и уверенно даже когда неверен. Имена он обычно даёт неплохие, а вот «зачем» объяснить не может — этот комментарий пишете вы. И не отправляйте в репозиторий то, что не можете объяснить сами.
Как убедить команду, если решает не только моё мнение?
Не спорьте о вкусах — показывайте цену. Посчитайте, сколько времени ушло на разбор последнего инцидента из-за непонятного сообщения об ошибке, и предложите одно конкретное правило. Одно внедрённое правило убеждает лучше, чем длинный разговор о качестве кода вообще.
Итог
Больше всего даёт самое дешёвое: внятные имена и ранний выход вместо вложенности. Обе привычки ничего не стоят и меняют ощущение от кода сразу.
Споры о стиле закройте автоформатированием и займитесь тем, что действительно важно: понятными сообщениями об ошибках и комментариями, объясняющими решения. Через полгода вы скажете себе спасибо — вы и есть главный читатель этого кода.
Комментарии
0Будьте первым, кто ответит автору.