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



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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

https://habrahabr.ru/post/335400/