Привет Хабр! Предлагаю вашему вниманию свободный перевод статьи «Good code is its own best documentation» от Amit Shekhar.
Хороший код, как хорошая шутка — не требует объяснений.
Если ваш код прост и понятен, то по большей части, к нему не нужно комментариев и документации.
Хороший код похож на автомобиль с отличным стерео и подстаканниками, который без проблем разгоняется до предела. Когда он ломается, любой механик может исправить его в короткие сроки, используя обычные инструменты.
Плохой код похож на автомобиль, который обещает быть в состоянии достигнуть 120 км/ч, но имеет стерео, который принимает только кассетные ленты, а подстаканники имеют наклонные днища. Каждый раз, когда вы пытаетесь настроить зеркала, автомобиль взрывается в пламени и должен быть отремонтирован конкретным человеком, который собрал его на сборочной линии, используя свои уникальные инструменты.
Покажите ваш код другому программисту, который его еще не видел, и пусть он попробует объяснить, что выполняет каждый модуль, а вы внимательно слушайте.
Чем больше вам хочется перебить и объяснить по-своему, тем, скорее всего, хуже ваш код.
Если вы можете спокойно и молча слушать, а человек рядом с вами все объясняет и не задает вопросов, возможно, ваш код хорош.
Допустим, в вашем проекте есть три слоя — внутренний, средний и внешний.
Ваш внутренний слой не должен ничего знать о вашем среднем или внешнем слое. Ваш средний слой не должен ничего знать о вашем внешнем слое.
Таким образом, ваш внутренний кодовый слой может быть протестирован независимо от других.
Подробнее об этом читайте в этой статье (Ссылка переводчика)
“Хороший код — наша лучшая документация” — Steve McConnell
Хороший код, как хорошая шутка — не требует объяснений.
Если ваш код прост и понятен, то по большей части, к нему не нужно комментариев и документации.
Хороший код похож на автомобиль с отличным стерео и подстаканниками, который без проблем разгоняется до предела. Когда он ломается, любой механик может исправить его в короткие сроки, используя обычные инструменты.
Плохой код похож на автомобиль, который обещает быть в состоянии достигнуть 120 км/ч, но имеет стерео, который принимает только кассетные ленты, а подстаканники имеют наклонные днища. Каждый раз, когда вы пытаетесь настроить зеркала, автомобиль взрывается в пламени и должен быть отремонтирован конкретным человеком, который собрал его на сборочной линии, используя свои уникальные инструменты.
Хороший код похож на хорошо написанный учебник
- Прост и понятен
- Удобно разбит на главы, каждая из которых посвящена четко определенной теме
Плохой код похож на плохо написанный учебник
- Все главы ссылаются друг на друга, и непонятно, о чем вообще идет речь
- Снова и снова рассказывается об одном и том же, причем причин для этого нет
- Автор упоминает несколько исключений из правил, при этом часто противоречит сам себе
- Внезапно появляется вампир! Он искрится на солнце
Вот о чем важно не забывать, если хотите написать хороший код:
- Наглядность — для вас и каждого, кто решит заглянуть в ваш код
- Возможность поддержки — ваш код должен быть легко модифицируемым
- Простота — не стоит все беспричинно усложнять
- Эффективность — ваш код должен работать настолько быстро, насколько это вообще возможно
- Понятность — если ваш код прост и понятен, в большинстве случаев комментариев не требуется вовсе. Выбирайте такие названия свойств и методов, чтобы сразу было понятно что он делает
- Низкое соотношение возмущений и удивленных возгласов в минуту — минимизирует частоту, с которой другой разработчик будет читать ваш код и говорить «WTF?!»
Проверка качества кода
Покажите ваш код другому программисту, который его еще не видел, и пусть он попробует объяснить, что выполняет каждый модуль, а вы внимательно слушайте.
Чем больше вам хочется перебить и объяснить по-своему, тем, скорее всего, хуже ваш код.
Если вы можете спокойно и молча слушать, а человек рядом с вами все объясняет и не задает вопросов, возможно, ваш код хорош.
Признаки хорошего кода:
- Он выглядит умным, но не заумным
- Вы можете вернуться к написанию кода после выходных, и сразу приступить к работе без переосмысливания написанного
- Алгоритмы оптимальны по скорости и по удобочитаемости
- Классы, переменные и функции названы так, что не нужно напрягать мозг, чтобы понять, зачем они нужны
- Каждый из ваших классов предназначен для одной, ясно выраженной цели, и отделен от других классов
- Ваши методы короткие – в идеале короче 50 строк, и уж точно не больше 100
- Методы предназначены для выполнения одной задачи
- Названия методов однозначно определяют то, что они делают, и вам не нужно смотреть на код внутри этого метода
- Если нужно вернуться и добавить/модифицировать какую-нибудь функцию, это не должно вызывать затруднений
- Ваши try/catch блоки малы настолько, насколько это возможно
- Unit-тесты пишутся легко и без особых усилий
Хороший код является модульным
Допустим, в вашем проекте есть три слоя — внутренний, средний и внешний.
Ваш внутренний слой не должен ничего знать о вашем среднем или внешнем слое. Ваш средний слой не должен ничего знать о вашем внешнем слое.
Таким образом, ваш внутренний кодовый слой может быть протестирован независимо от других.
Подробнее об этом читайте в этой статье (Ссылка переводчика)
“Хороший код — наша лучшая документация” — Steve McConnell
