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

java-source-code

Хороший код , как хорошая шутка — не требует объяснений.

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

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

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

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




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

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

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

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




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

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

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

Вот признаки хорошего кода:

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

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




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

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

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

Подробнее об этом читайте в этой статье .

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

Источник: Good code is its own best documentation.

Комментарии:

Добавить комментарий

Ваш e-mail не будет опубликован. Обязательные поля помечены *