Хороший код — наша лучшая документация

Habrahabr

Привет Хабр! Предлагаю вашему вниманию свободный перевод статьи «Good code is its own best documentation» от Amit Shekhar.

image

Хороший код, как хорошая шутка — не требует объяснений. Если ваш код прост и понятен, то по большей части, к нему не нужно комментариев и документации.

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

Плохой код похож на автомобиль, который обещает быть в состоянии достигнуть 120 км/ч, но имеет стерео, который принимает только кассетные ленты, а подстаканники имеют наклонные днища. Каждый раз, когда вы пытаетесь настроить зеркала, автомобиль взрывается в пламени и должен быть отремонтирован конкретным человеком, который собрал его на сборочной линии, используя свои уникальные инструменты.

Хороший код похож на хорошо написанный учебник

  • Прост и понятен
  • Удобно разбит на главы, каждая из которых посвящена четко определенной теме

Плохой код похож на плохо написанный учебник

  • Все главы ссылаются друг на друга, и непонятно, о чем вообще идет речь
  • Снова и снова рассказывается об одном и том же, причем причин для этого нет
  • Автор упоминает несколько исключений из правил, при этом часто противоречит сам себе
  • Внезапно появляется вампир! Он искрится на солнце

Вот о чем важно не забывать, если хотите написать хороший код:

  • Наглядность —  для вас и каждого, кто решит заглянуть в ваш код
  • Возможность поддержки — ваш код должен быть легко модифицируемым
  • Простота  —  не стоит все беспричинно усложнять
  • Эффективность  —  ваш код должен работать настолько быстро, насколько это вообще возможно
  • Понятность — если ваш код прост и понятен, в большинстве случаев комментариев не требуется вовсе. Выбирайте такие названия свойств и методов, чтобы сразу было понятно что он делает
  • Низкое соотношение возмущений и удивленных возгласов в минуту — минимизирует частоту, с которой другой разработчик будет читать ваш код и говорить «WTF?!»

Проверка качества кода

Покажите ваш код другому программисту, который его еще не видел, и пусть он попробует объяснить, что выполняет каждый модуль, а вы внимательно слушайте.

Чем больше вам хочется перебить и объяснить по-своему, тем, скорее всего, хуже ваш код.

Если вы можете спокойно и молча слушать, а человек рядом с вами все объясняет и не задает вопросов, возможно, ваш код хорош.

Признаки хорошего кода:

  • Он выглядит умным, но не заумным
  • Вы можете вернуться к написанию кода после выходных, и сразу приступить к работе без переосмысливания написанного
  • Алгоритмы оптимальны по скорости и по удобочитаемости
  • Классы, переменные и функции названы так, что не нужно напрягать мозг, чтобы понять, зачем они нужны
  • Каждый из ваших классов предназначен для одной, ясно выраженной цели, и отделен от других классов
  • Ваши методы короткие – в идеале короче 50 строк, и уж точно не больше 100
  • Методы предназначены для выполнения одной задачи
  • Названия методов однозначно определяют то, что они делают, и вам не нужно смотреть на код внутри этого метода
  • Если нужно вернуться и добавить/модифицировать какую-нибудь функцию, это не должно вызывать затруднений
  • Ваши try/catch блоки малы настолько, насколько это возможно
  • Unit-тесты пишутся легко и без особых усилий

Хороший код является модульным

Допустим, в вашем проекте есть три слоя — внутренний, средний и внешний.

Ваш внутренний слой не должен ничего знать о вашем среднем или внешнем слое. Ваш средний слой не должен ничего знать о вашем внешнем слое.

Таким образом, ваш внутренний кодовый слой может быть протестирован независимо от других.

Подробнее об этом читайте в этой статье (Ссылка переводчика)

“Хороший код — наша лучшая документация” — Steve McConnell