писать код надо так как будто
Не комментируйте свой код — перепишите его
Я считаю, что комментарии относятся к признакам «кода с запашком» и должны использоваться крайне экономно и только там, где они на самом деле нужны.
Так что же нужно комментировать?
Вообще, я не сказал, что комментарии не нужны совсем, в программировании довольно редко используются какие-либо абсолютные соглашения. Вы должны быть уверены, что есть на самом деле весомая причина использования пояснений в коде. Я использую их как предупреждающие знаки о том, что программисту стоит обратить особое внимание на этот участок. Скорее всего, он чем-то опасен или делает какую-то неочевидную вещь. Можно ли сказать то же самое про любой кусок кода, который чем-то сложен и сильно запутан? Да, можно! По этой причине я часто использую комментарии в legacy-коде, над которым не ведётся активная работа. Т.к. из-за внешних бизнес-условий мы не всегда можем проводить рефакторинг так часто, как хотелось бы, да и иногда лучше просто не трогать то, что и так работает, то комментарии могут быть полезны. Я считаю, что в данном случае это необходимое зло.
Почему же комментарии — это зло?
Короткий ответ в том, что они часто врут нам. Они говорят, что делает данный код и часто могут не изменяться в последующих ревизиях. Например, есть функция, которая возвращает string, и я так и написал в комментариях. Но затем потребовалось изменить её, и какой-то другой программист внёс быстрые правки, поменяв тип возвращаемого значения на int, но забыл обновить комментарии. Это довольно распространённый случай. Вот мы и пришли к ситуации, когда комментарии говорят одно, а происходит на самом деле совсем другое.
Мы знаем, что правда всегда на стороне кода. Ведь это именно то, что будет происходить в реальном продукте. Так зачем же читать комментарии, которые потенциально могут быть ошибочны и тратить время на них, когда можно просто посмотреть на код и понять, что он делает?
Код никогда не лжёт, комментарии иногда делают это. — Ron Jeffries
Как писать код так, чтобы комментарии были не нужны?
В проектах, которые активно разрабатываются, я стараюсь писать код так, чтобы он выражал то, что он должен делать. Это, пожалуй, то, на что я трачу большую часть своего времени. Иногда мне со значительным трудом даётся выбор названий. Обычно я стараюсь выбирать такое имя для функции или класса, которое напрямую отражает то, что они делают, а позже переименовываю, если это необходимо.
Отрывок выше является хорошим примером выразительного кода. Даже ребёнок сможет понять, что это собака, и она может лаять. Конечно, в большинстве случаев реальный код намного сложнее и далеко не так очевидно, как написать его правильно, но общие принципы везде одинаковые. Старайтесь давать имена сущностям так, как будто вам надо будет объяснить это ребёнку. В данном примере мы можем описать код как «собака умеет лаять». Точно так же можно сказать «пользователь может залогиниться» или «пользователь может изменить данные своего профиля».
Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живёте. — Martin Golding
Эта цитата всегда казалась мне забавной, пока я сам не столкнулся с сопровождением кода, написанного просто ужасно. Мне на самом деле хотелось как следует врезать его автору за то, что он сделал код настолько сложным для сопровождения. Простые изменения, которые заняли бы минут 20 в коде с хорошей архитектурой, растянулись на 4 часа.
Внимательно относитесь к именам переменных, функций и классов
Нет ничего необычного в том, чтобы в процессе разработки изначальное название функции или переменной изменялось несколько раз. Особенно, если цикл разработки продолжается более, чем один день. Если мне пришла в голову мысль о том, как можно более правильно назвать что-либо, я вернусь к этому участку кода и потрачу время на его изменение. Всякий раз, когда мне кажется, что комментарий был бы здесь очень кстати, я возвращаюсь на шаг назад и еще раз смотрю на написанный код. Иногда даже консультируюсь с коллегой, чтобы понять, насколько комментарии всё-таки оправданы здесь. Иногда комментарии побеждают, но обычно, если это не какой-то очень специфичный участок кода, они всё-таки не нужны.
Любой дурак может написать код, понятный компьютеру. Хорошие программисты пишут код, понятный людям. — Martin Fowler
В этой цитате Мартин Фаулер описал всю суть того, почему нужно избегать комментариев. Ваш код должен быть настолько хорошо читаемым, что любой другой программист смог бы разобраться в нём. А комментарии просто кричат о том, что вы не сможете понять эту строчку без дополнительных пояснений. Вот почему я избегаю их, и вам советую поступать так же.
В следующий раз, когда вы будете писать код, постарайтесь делать это без комментариев вообще. Затем, через некоторое время, взгляните на программу и подумайте, насколько легко её читать. Если возникают трудности и вы не можете понять, что вы сами же написали без комментариев, просто выкиньте всё и перепишите с нуля.
Хинт для программистов: если зарегистрируетесь на соревнования Huawei Cup, то бесплатно получите доступ к онлайн-школе для участников. Можно прокачаться по разным навыкам и выиграть призы в самом соревновании.
Перейти к регистрации
Писать код надо так как будто
Не зависимо от экономических подъемов и спадов хороших программистов всегда не хватает, а жизнь слишком коротка, чтобы тратить ее на работу в отсталом учреждении при наличии множества лучших вариантов.
Программисты склонны рассматривать менеджеров как низшую ступень технической эволюции, где-то между одноклеточными организмами и мамонтами, вымершими в ледниковый период.
Помните! Тестирование может указать только на наличие, но не отсутствие ошибок.
Похвалите себя за чтение этой книги. За это время вы продвинулись вперед гораздо дальше, чем большинство ваших коллег, потому что объем этой книги превышает годичный объем чтения большинства программистов.
Новые инструменты полезны, но они не заменяют ясность мышления.
Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живете.
«Когда вместе собираются критики, они говорят о Теме, Композиции и Идее. Когда вместе собираются художники, они говорят о том, где купить дешёвый скипидар».
Пабло Пикассо.
Если требования [к проекту] нестабильны, рассматривайте работу над ними как отдельный проект.
Джон Бентли говорит, что программист должен быть способен сесть у камина со стаканом бренди, хорошей сигарой, охотничьей собакой у ног и «сформулировать программу» подобно тому, как писатели создают романы.
«Планируйте выбросить первый экземпляр программы: вам в любом случае придется это сделать »
Фред Вруне
«Если вы планируете выбросить первый экземпляр программы, то выбросите и второй»
Крейг 3еруни
При инкрементной разработке вы сначала создаете самую простую версию системы, которую можно было бы запустить. Она может не принимать реальных данных, может не выполнять над ними реальных действий, может не генерировать реальные результаты — она должна быть просто скелетом, достаточно крепким,чтобы поддерживать реальную систему по мере ее разработки. Она может вызывать поддельные классы для каждой из определенных вами основных функций. Такая система похожа на песчинку, с которой начинается образование.
За ошибку, допущенную при создании простого объекта, приходится расплачиваться лишь потраченным временем и, возможно, некоторым разочарованием
Неудачное определение проблемы грозит пустой тратой времени на решение не той проблемы. Разумеется, нужную проблему вы при этом тоже не решите.
Думая о новой функции, клиенты приходят в возбуждение. Кровь у них разжижается, переполняет продолговатый мозг, и они впадают в эйфорию, забывая обо всех собраниях, посвященных обсуждению требований, о церемонии подписания и всех документах. Угомонить таких одурманенных новыми функциями людей проще всего, заявив: «Ого, это действительно прекрасная идея! Но ее нет в документе требований, поэтому я должен пересмотреть график работы и смету, чтобы вы могли решить, хотите ли вы реализовать это прямо сейчас или позднее». Слова «график» и «смета» отрезвляют куда лучше, чем кофе и холодный душ, и многие требования быстро превращаются в пожелания.
В свое время Данте отвел нижний круг ада самому Сатане.
Но с тех пор кое-что изменилось, и сейчас Сатана охотно делит нижний круг с программистами, не умеющими эффективно отлаживать программы.
Как написать код, который полюбят все
Набор практик хорошего кода, не зависящих от языка программирования, опубликовал сайт proglib.io. Примените их, и ваш код будет не только работать, но и читаться.
Программисты в первую очередь работают с языком. Поэтому написание программ похоже на любой другой вид письменной работы. Сначала вы излагаете свои мысли как есть, а затем «причесываете» до тех пор, пока текст не будет легко читаться. Качество кода – результат проявления небезразличного отношения к делу и показатель профессионализма.
Почему важна читаемость кода
Чтение кода происходит чаще, чем написание. Есть большая разница между обучением программированию и реальной работой в компании. Вначале мы и пишем, и читаем собственные программы. Но чем дальше мы продвигаемся, тем чаще нам приходится не писать, а читать код. Чем легче код читается, тем проще с ним работать другим людям.
«Пишите код так, как будто сопровождать его будет склонный к насилию психопат, который знает, где вы живете», — Джон Вуд в доске обсуждений по C++, 1991 г.
Чем проще читать код, тем проще его сопровождать. Понятный, читаемый код легче тестировать, в нем легче отлавливать ошибки – они не скрываются в его запутанной структуре. Плохо оформленный код неприятно изучать, читать, тестировать, сложно дополнять. Рано или поздно плохой код становится проще переписать.
Эстетическое восприятие кода влияет на удобство работы. Казалось бы, гораздо важнее производительность, возможность модификации, расширения… Но все эти показатели улучшаются, если код соответствует нашему чувству прекрасного. Глядя на качественно написанный код, можно быстро понять алгоритм и то, как работает программа для разных входных данных. Чистый код читается как хорошо написанная проза: слова превращатся в зрительные образы.
Стиль кода определяет его будущее. Стиль и дисциплина продолжают жить в коде, даже если в нем не осталось ни одной исходной строки.
С чего начать: документация по стилю оформления кода
Все дороги программиста ведут к документации. В каждом языке существует свой стандарт оформления кода. Для Python используется документ PEP-8, для PHP – стандартные рекомендации PSR-1 и PSR-2, для Java – Java Coding Conventions, для JavaScript – Airbnb JavaScript Style Guide или Google JavaScript Style Guide. Документ для вашего языка вы найдете по поисковому запросу Code Style.
Когда вы работаете в группе разработчиков, нужно использовать принятые в команде правила. Стиль должен быть единым, как будто код был написан одним здравомысленным человеком.
В популярных IDE заложена возможность автоматической настройки стиля кода под стандарты – общие или предложенные командой. Разберитесь, как настроить среду под необходимое оформление. Потраченное время сэкономит многие часы рутинной работы.
Применение стандартов – лучший подход для новичка. Читающий не будет отвлекаться на оформление и сразу погрузится в тонкости выбранных подходов, а не расстановок переносов. Изложенные ниже правила понадобятся для того, чтобы понять, как действовать в тех случаях, когда стандарт не дает никаких рекомендаций.
Роберт Мартин «Чистый код. Создание, анализ и рефакторинг»
Конечно, мы не могли обойтись без упоминания замечательной книги Роберта Мартина о чистом коде и анализе программ. В ней приводятся примеры для языка Java, но большинство идей справедливы для любых языков.
Всё что изложено ниже, в значительной мере представляет сжатый конспект этой книги с дополнениями из нашего опыта в проектировании программ. Итак, приступим к практикам.
Главное правило чистого кода: выразительные имена
Содержательность. К выбору названий любых объектов нужно подходить со всей ответственностью. Выразительные имена позволяют писать код, не требующий комментариев.
Полезно не только исходно выбирать ясные имена, но и заменять названия на более удачные, если они нашлись позже. Современные среды программирования позволяют легко заменить название переменной во всём коде, так что это не должно быть проблемой.
В первом примере непонятно, что вообще происходит, хотя в этом коде нет ни сложных выражений, ни каких-либо странностей. В результате правок сам код никак не изменился. Если знать, что это часть игры «Сапер», то теперь из кода понятно: здесь обрабатывается список ячеек игрового поля. Этот код можно улучшать и далее, но уже в результате простого переименования стало понятно, что происходит.
Избегайте любых двусмысленностей и ложных ассоциаций. Если в объекте перечисляется список, но сам объект не является списком, нельзя в составе его названия употреблять слово list – это запутывает читающего.
Остерегайтесь малозаметных различий – имена объектов должны существенно отличаться друг от друга. По этой причине плохи длинные имена с повторяющимся элементами – чтобы сличить их друг с другом, тратятся лишние силы и время. Избегайте использования в именах переменных строчной буквы L и прописных I, O – они часто путаются с единицей и нулем.
Имя должно легко произноситься. Используйте для названий слова. Если названия состоят из сокращений, каждый начинает произносить их по-своему, что затрудняет взаимопонимание. А при чтении кода каждый раз «спотыкаешься» о такое название.
Имя должно быть удобным для поиска. Слишком короткие имена трудно искать в большом объеме текста. Однобуквенные имена можно использовать только для локальных переменных в коротких методах и счетчиков циклов ( i, j, k ). Обычно называя объект одной буквой, вы всего лишь создаете временный заменитель. Но не бывает ничего более постоянного, чем что-то «временное». Проверяйте грамотность написания выбранных слов.
Не стоит следовать этому правилу, как и любому другому, безоговорочно. В формулах некоторые константы лучше воспринимаются в числовой записи.
Ваш код будут читать программисты. Не стесняйтесь использовать термины из области информатики, общепринятые названия алгоритмов и паттернов. Такие имена сообщают информацию быстрее, чем сам код.
Избегайте остроумия и каламбуров в названиях. Шутки имеют свойство быть понятными лишь ограниченное время и для конкретной аудитории, знакомой с первоисточником. Отдавайте предпочтение ясности перед развлекательностью. Шутки можно приберечь для презентации, которая происходит «здесь и сейчас». Хороший код способен выйти далеко за границы вашей культуры.
Рабочие среды продолжают развиваться. Уже нет никакой необходимости кодировать типы в именах, создавать префиксы для членов классов. Всю нужную информацию можно получить из цветового выделения или контекстно-зависимых подсказок сред разработки. Добавление префиксов убивает удобство поиска по автовыполнению – выпадает слишком много имен, начинающихся с одинаковых символов.
Функции
Компактность. Уже в 80-е годы считалось, что функция должна занимать не более одного экрана. Экраны VT100 тогда состояли из 24 строк и 80 столбцов. В наши дни на экране можно разместить гораздо больше инорфмации, но лучше ограничиться тем же объемом. Самоограничение позволяет видеть точку объявления каждой используемой переменной и держать в уме всю «историю», которую рассказывает функция.
Вполне вероятно, что тот, кто будет сопровождать ваш код, не будет иметь возможности работать на большом мониторе. Например, ему необходимо одновременно разместить на одном рабочем столе экрана ноутбука несколько окон. Среды разработки позволяют установить ограничение, «верхнюю планку» (то есть правую 😉 ).
Правило одной операции. Плохой код пытается сделать слишком много всего, намерения программиста расплываются для читателя. Поэтому стоит ввести важное правило:
Функция должна выполнять только одну операцию, выполнять ее хорошо, и ничего другого она делать не должна.
Каждая функция должна делать то, что вы от нее ожидали из названия. Если функция действует не так, как она названа, читатель кода перестает доверять автору программы, ему приходится самостоятельно разбираться во всех подробностях реализации.
«Я люблю, чтобы мой код был элегантным и эффективным. Логика должны быть достаточно прямолинейной, чтобы ошибкам было трудно спрятаться; зависимости — минимальными, чтобы упростить сопровождение; обработка ошибок — полной в соответствии с выработанной стратегией; а производительность — близкой к оптимальной, чтобы не искушать людей загрязнять код беспринципными оптимизациями. Чистый код хорошо решает одну задачу», — Бьёрн Страуструп, создатель языка С++
К тому же при использовании исключений код обработки ошибок изолируются от ветви нормального выполнения. Сами блоки лучше выделять в отдельные функции. Вместе с исключением нужно передавать контекст ошибки – сообщение, содержащее сведения об операции и типе сбоя.
Соблюдайте уровни абстракции. Одна функция – один уровень абстракции. Смешение уровней абстракции создает путаницу, функция обрастает слишком большим количеством второстепенных подробностей. Старайтесь соблюдать ясную иерархию.
Код читается сверху вниз. По мере чтения уровни абстракции должны меняться равномерно. Каждая функция должна быть окружена функциями единого уровня абстракции.
Ограничивайте число аргументов. Чем больше аргументов у функции, тем сложнее с ней работать. Необходимость функций с количеством аргументов большим двух должна быть подкреплена очень вескими доводами. Каждый новый аргумент критически усложняет процедуру тестирования. Если функция должна получать более двух аргументов, скорее всего, эти аргументы образуют концепцию, заслуживающую собственного имени.
Комментарии
Это непопулярное мнение, но в большинстве случаев комментарии – зло. Код должен быть самодокументированным. Комментарий – всегда признак неудачи: мы не смогли написать код так, что он понятен без комментариев. Проверьте, можно ли выразить свое намерение в самом коде.
В чём проблема? Программисты умеют сопровождать код, но не комментарии. В растущем коде комментарии быстро устаревают, частично или полностью переставая соответствовать ситуации. Только код правдиво сообщает своим содержанием, что он в действительности делает. Лучше потратить время на исправление запутанного кода, чем добавлять к плохому коду комментарии.
Однако есть несколько видов комментариев, которые выглядят достаточно оправданными.
TODO-комментарии. Бывает так: нужно было успеть к дедлайну, пришлось писать код быстро, поэтому в нем остались дыры. То есть всё работает, но реализация ущербная. Укажите все недоработки и создайте под них задачи. Каждый комментарий указывает на недоработку или потенциальную уязвимость.
Юридические комментарии. Корпоративные стандарты могут принуждать вставлять комментарии по юридическим соображениям. Ограничьтесь в таком комментарии описанием лицензии и ссылкой на внешний документ.
Предупреждения о последствиях. Иногда бывает полезно предупредить других программистов о нежелательных последствиях:
Комментарий также может подчеркивать важность обстоятельства, которое на первый взгляд кажется несущественным.
По-настоящему плохие комментарии
Бывают такие типы комментариев, которые лучше никогда не делать.
Закомментированный программный код. «Когда-нибудь в будущем расскомментирую этот код, приведу всё в порядок. Или вдруг эта идея кому-то поможет». Любой закомментированный код только ухудшает ситуацию. Все изменения хранятся в контроле версий – удаляйте такой код на корню. Это просто мусор: «потом» равносильно «никогда». Если что-то действительно нужно сделать, создайте краткий TODO-комментарий и задачу.
Мертвые функции – идентичные по смыслу предыдущему пункту функции и методы, которые не вызываются в программе. Пользуйтесь системой контроля версий и без зазрений совести удаляйте любой код, который не используется во время выполнения программы.
Избыточные комментарии. Задайте себе вопрос: стал ли код понятнее после прочтения комментария? Часто комментарии просто загромождают код и скрывают его смысл, излагая очевидные вещи. Иногда в комментарии включаются описания не относящихся к делу подробностей. Но профессионал бережет не только свое, но и чужое время, и не отвлекает читающего без повода.
Журнальные комментарии и ссылки на авторов. Некоторые программисты добавляют комментарий в начало файла при редактировании. Или указывают, кто и когда внес исправления. Когда-то это было оправдано, но теперь у нас есть системы контроля версий – это гораздо лучший способ обозначить границы зоны ответственности каждого.
Позиционные маркеры. Иногда любят отмечать определенные группы и позиции в исходных файлах:
Качественно организованный код способен внятно рассказать историю без балластных заголовков.
Уровень файлов программ
Минималистичность. Чем меньше кода, тем лучше. Имя файла должно быть простым, но содержательным. Маленькие файлы обычно более понятны, чем большие. Но размер файла, конечно, не должен быть самоцелью.
Код должен быть максимально линейным. Чем больше вложенность кода, тем сложнее его читать. Следите за тем, как двигаются ваши глаза. В хорошем коде вы двигаетесь строка за строкой, лишь изредка возвращаясь к предыдущим строчкам. Вложенность более трех уровней указывает на то, что с кодом нужно поработать: переписать условия проверок и циклов (использовать return и функциональное программирование), разбить код на меньшие методы.
Отдельные «мысли» следует отделять друг от друга пустыми строками. Каждая пустая строка – зрительная подсказка: описание одной концепции закончилось, далее следует новая. При просмотре кода взгляд концентрируется на первых строчках – в них больше всего информации, как в началах абзацев этого текста.
Тесно связанные концепции, должны располагаться вблизи друг друга. Не заставляйте читателя прыгать между файлами или постоянно скроллить файл. По той же причине переменные нужно объявлять как можно ближе к месту использования. Однако переменные экземпляров лучше объявлять в одном месте, обычно в начале класса (то есть в одном месте), так как в хорошо спроектированном классе переменные используются большинством методов класса.
Пробелы для группировки взаимосвязанных элементов. Пробелы улучшают читаемость кода, если они стоят вокруг операторов присваивания, после запятых при перечислении переменных. В формулах пробелы используются для подчеркивания приоритета: не ставятся между множителями, но отбивают знаки сложения и вычитания.
Отступы. Размер отступов должен соответствовать позиции кода в иерархии. Это общая практика, которая позволяет быстро пропускать области видимости, не относящиеся к текущей ситуации. Не поддавайтесь искушению нарушить правила расстановки отступов для коротких команд.
Некоторые замечания по поводу архитектуры и тестов
В системе должны выполняться все тесты. Тесты – главный способ, с помощью которого можно понять, что система контролируема. А только контролируемую систему можно проверить.
Три закона тестирования по методологии TDD. Тестовый код не менее важен, чем код продукта. Соблюдение следующих трех правил позволяет организовать работу так, чтобы тесты охватывали все аспекты кода продукта:
F.I.R.S.T. Качественные тесты должны обладать пятью характеристиками, первые буквы которых образуют указанный акроним:
Повышение уровня абстракции и устранение дубликатов. Все программы состоят из очень похожих элементов, а все задачи программирования сводятся к работе с ограниченным набором действий. Многие из этих действий могут быть описаны в одних и тех же терминах, например, извлечение элемента из коллекции. В подобных ситуациях правильно инкапсулировать реализацию в более абстрактном классе. Повышение уровня абстракции позволяет избежать дублирования и многократно применения одного и того же кода, лучше понять, что действительно происходит в программе, уйдя от частностей.
Если что-то в программе делается снова и снова, значит, какая-то важная концепция не нашла своего отражения в коде. Нужно попытаться понять, что это такое, и выразить идею в виде кода. Избегайте дубликатов, это всегда лишняя работа, лишний риск, лишняя сложность.
Несколько языков в одном исходном файле. Современные среды программирования позволяют объединять в одном файле код, написанный на разных языках. Результат получается запутанным, неаккуратным и ненадежным. Чтобы четко разграничить ответственность, в файле должен преобладать один язык. Сведите к минимуму количество и объем кода на дополнительных языках.
Не нужно бездумно следовать догмам. Не переусердствуйте с сокращением кода функций и классов. Всегда руководствуйтесь здравым смыслом.
Заключение
Чистый код выглядит так, как если его автор над ним тщательно потрудился. Вы не можете найти очевидных возможностей для его улучшения. Попытавшись его улучшить, вы вновь вернетесь к тому же коду.
Чтобы писать чистый код, который бы никого не удивлял, необходимо раз за разом сознательно применять описанные приемы. При чтении чистого кода вы улыбаетесь, как при виде искусно сделанной музыкальной шкатулки. Код можно назвать красивым, если у вас создается впечатление, что язык был создан специально для этой задачи.