Как писать самодокументируемый код

Каждый раз, когда я вижу в коде комментарий // увеличиваем x на 1 или трёхэтажную простыню текста, объясняющую древний костыль, у меня дёргается глаз. Правило "хороший код документирует себя сам" часто понимаю неверно, превращая проект либо в выжженную пустыню, либо в нагромождение перегруженных функций.

Главный секрет прост. Код должен отвечать на вопрос "что происходит?", а комментарии "почему?". Если логика неочевидна, не нужно расписывать шаги. Вместо этого замените магические числа константами и выносите сложные условия в переменные с говорящими названиями. Писать комментарий стоит только тогда, когда вы зашили в код вынужденный хак из-за багов внешнего API или обошли специфическое ограничение архитектуры.

Чтобы код читался как книга, соблюдайте правило одного уровня абстракции (SLAP). Не перемешивайте в одной функции высокоуровневую бизнес-логику и низкоуровневый парсинг строк. Главная функция должна лишь координировать этапы (получить данные, проверить права, отправить уведомление), делегируя детали специализированным методам.

Избавляйтесь от бесконечно вложенных if-else. Используйте ранние возвраты, отсекая ошибки и пограничные случаи в самом начале функции. Это выпрямляет логику, оставляя успешный сценарий на виду. И обязательно используйте строгую типизацию - интерфейсы и DTO скажут коллегам на ревью гораздо больше, чем устаревший текст в README, потому что за типами следит компилятор.

Перед пулл-реквестом посмотрите на код свежим взглядом. Если суть ясна из одних названий функций и аргументов - вы справились.