- PVSM.RU - https://www.pvsm.ru -
Привет! Предлагаю вашему вниманию свободный перевод статьи «Good code is its own best documentation [1]» от Amit Shekhar [2].
Хороший код, как хорошая шутка — не требует объяснений.
Если ваш код прост и понятен, то по большей части, к нему не нужно комментариев и документации.
Хороший код похож на автомобиль с отличным стерео и подстаканниками, который без проблем разгоняется до предела. Когда он ломается, любой механик может исправить его в короткие сроки, используя обычные инструменты.
Плохой код похож на автомобиль, который обещает быть в состоянии достигнуть 120 км/ч, но имеет стерео, который принимает только кассетные ленты, а подстаканники имеют наклонные днища. Каждый раз, когда вы пытаетесь настроить зеркала, автомобиль взрывается в пламени и должен быть отремонтирован конкретным человеком, который собрал его на сборочной линии, используя свои уникальные инструменты.
Покажите ваш код другому программисту, который его еще не видел, и пусть он попробует объяснить, что выполняет каждый модуль, а вы внимательно слушайте.
Чем больше вам хочется перебить и объяснить по-своему, тем, скорее всего, хуже ваш код.
Если вы можете спокойно и молча слушать, а человек рядом с вами все объясняет и не задает вопросов, возможно, ваш код хорош.
Допустим, в вашем проекте есть три слоя — внутренний, средний и внешний.
Ваш внутренний слой не должен ничего знать о вашем среднем или внешнем слое. Ваш средний слой не должен ничего знать о вашем внешнем слое.
Таким образом, ваш внутренний кодовый слой может быть протестирован независимо от других.
Подробнее об этом читайте в этой статье [4](Ссылка переводчика [5])
“Хороший код — наша лучшая документация” — Steve McConnell
Автор: velkonost
Источник [6]
Сайт-источник PVSM.RU: https://www.pvsm.ru
Путь до страницы источника: https://www.pvsm.ru/programmirovanie/262071
Ссылки в тексте:
[1] Good code is its own best documentation: https://blog.mindorks.com/good-code-vs-bad-code-263f71e867c1
[2] Amit Shekhar: https://blog.mindorks.com/@amitshekhar
[3] мозг: http://www.braintools.ru
[4] этой статье : https://8thlight.com/blog/uncle-bob/2012/08/13/the-clean-architecture.html
[5] Ссылка переводчика: https://habrahabr.ru/post/133287/
[6] Источник: https://habrahabr.ru/post/335400/
Нажмите здесь для печати.