Как сделать код html читабельным
Как сделать код читабельным
Когда-нибудь мы все писали (а некоторые и пишут) плохой код, и, надеюсь, мы все работаем над улучшением наших навыков, а не просто чтением статей вроде этой.
Зачем нам писать хороший код, а не просто производительный код?
Хотя производительность вашего продукта или сайта важна, также важно и то, как выглядит ваш код. Причиной этого является то, что не только машина читает ваш код.
Во-первых, рано или поздно вам придется перечитывать собственный код, и когда это время наступит, только хорошо написанный код поможет вам понять, что вы написали, или выяснить, как это исправить.
Во-вторых, если вы работаете в команде или сотрудничаете с другими разработчиками, то все члены команды будут читать ваш код и пытаться интерпретировать его так, как они понимают. Чтобы сделать это проще для них, важно соблюдать некие правила при названии переменных и функций, ограничивать длину каждой строки и сохранять структуру вашего кода.
Наконец, давайте рассмотрим конкретный пример.
Часть 1: Как определить плохой код?
Самый простой способ определить плохой код, на мой взгляд, — попытаться прочитать код так, как если бы это было предложение или фраза.
Например, взглянем на этот код:
Скриншот плохой версии функции «traverseUpUntil»
Представленная выше функция принимает некий элемент и условную функцию и возвращает ближайший родительский узел, который удовлетворяет условной функции.
Исходя из того, что код должен читаться, как обычный текст, первая строка имеет три грубейших недостатка.
Не совсем очевидно, что возвращается из-за неправильного имени переменной.
Часть 2: Давайте отрефакторим
Скриншот хорошей версии функции «traverseUpUntil»
Затем мы переходим к именам переменных:
Давайте попробуем прочитать: «Присвоить родительский узел родителя родителю, пока у родителя есть родительский узел, а функция условия не возвращает true». Уже гораздо понятнее.
Часто разработчики предпочитают использовать какую-то общую переменную ret (или returnValue ), но это довольно плохая практика. Если вы правильно назовёте свои возвращаемые переменные, становится очевидным то, что возвращается. Однако иногда функции могут быть длинными и сложными, что приводит к большой путанице. В этом случае я бы предложил разделить вашу функцию на несколько функций, и если она всё ещё слишком сложна, то, возможно, добавление комментариев может помочь.
Часть 3: Упрощение кода
Я просто убрал первую строку и заменил «parent» на «node». Таким образом, я пропустил ненужный шаг создания «parent» и перешёл прямо в цикл.
Но что насчёт имени переменной?
Хотя «node» не лучшее описание для этой переменной, оно удовлетворительное. Но давайте не будем останавливаться на этом, давайте переименуем её. Как насчёт «currentNode»?
Так-то лучше! Теперь, когда мы читаем метод, мы знаем, что currentNode всегда представляет собой узел, в котором мы сейчас находимся, вместо того, чтобы быть «каким-то» узлом.
Читабельность кода
С помощью кода создаются интерфейсы. Но и сам код — это интерфейс.
Несмотря на то, что читабельность кода очень важна, понятие это определено плохо — и часто в виде просто набора правил: использовать осмысленные имена переменных, большие функции разбивать на меньшие, применять стандартные шаблоны проектирования.
При этом наверняка всем приходилось иметь дело с кодом, который соответствует этим правилам, но почему-то представляет собой какую-то кашу.
Можно попытаться решить эту проблему, добавив новые правила: если имена переменных становятся очень длинными, нужно выполнить рефакторинг основной логики; если в одном классе накопилось множество вспомогательных методов, возможно, следует разделить его на два; нельзя применять шаблоны проектирования в неподходящем контексте.
Такие инструкции превращаются в лабиринт субъективных решений, и чтобы ориентироваться в нем, понадобится разработчик, который сможет делать правильный выбор — то есть, он уже должен уметь писать читабельный код.
Таким образом, набор инструкций — не выход. Поэтому нам придется сформировать более широкое представление о читабельности кода.
Для чего нужна читабельность
На практике под хорошей читабельностью обычно понимают, что код приятно читать. Однако на таком определении далеко не уедешь: во-первых, оно субъективно, во-вторых — привязывает нас к чтению обычного текста.
Нечитабельный код воспринимается как роман, который притворяется кодом: множество раскрывающих суть происходящего комментариев, простыни текста, которые нужно читать последовательно, умные формулировки, единственный смысл которых — быть «умными», боязнь повторного использования слов. Разработчик пытается сделать код читабельным, но нацеливается не на тот тип читателей.
Читабельность текста и читабельность кода — не одно и то же.
С помощью кода создаются интерфейсы. Но и сам код — это интерфейс.
Если код выглядит красиво, значит ли это, что он читабельный? Эстетичность — приятный побочный эффект читабельности, но как критерий не очень полезна. Возможно, в крайних случаях эстетика кода в проекте поможет удержать сотрудников — но с тем же успехом можно предложить хороший соцпакет. Кроме того, у каждого свое представление о том, что значит «красивый код». И со временем такое определение читабельности превращается в водоворот споров о табуляции, пробелах, скобках, «верблюжьей нотации» и т. п. Вряд ли кто-то потеряет сознание, увидев неправильные отступы, хотя это и привлекает внимание во время проверки кода.
Если код выдает меньше ошибок, можно ли считать его более читабельным? Чем меньше ошибок, тем лучше, но какой здесь механизм? Как сюда отнести расплывчатые приятные ощущения, которые испытываешь при виде читабельного кода? К тому же, сколько ни хмурь брови при чтении кода, ошибок это не добавит.
Если код легко править — он читабельный? А вот это, пожалуй, верное направление мысли. Меняются требования, добавляются функции, возникают ошибки — и в какой-то момент кому-то приходится править ваш код. А чтобы при этом не породить новые проблемы, разработчику нужно понимать, что конкретно он редактирует и как правки изменят поведение кода. Итак, мы нашли новое эвристическое правило: читабельный код должен легко редактироваться.
Какой код редактировать проще?
Сразу же хочется выпалить: «Код легче редактировать, когда имена переменных даются осмысленно», — но так мы просто переименуем «читабельность» в «удобство редактирования». Нам нужно более глубокое понимание, а не тот же набор правил в другом обличье.
Давайте начнем с того, что ненадолго забудем, что речь идет о коде. Программирование, которому несколько десятков лет, — лишь точка на шкале человеческой истории. Ограничившись этой «точкой», мы не сможем копнуть глубоко.
Поэтому посмотрим на читабельность через призму проектирования интерфейсов, с которыми мы сталкиваемся практически на каждому шагу — причем не только с цифровыми. Игрушка обладает функциональностью, которая заставляет ее кататься или пищать. У двери есть интерфейс, который позволяет открывать, закрывать и запирать ее. Данные в книге собраны в страницы, что обеспечивает более быстрый произвольный доступ, чем прокрутка. Изучая дизайн, об этих интерфейсах можно узнать намного больше — поинтересуйтесь у команды дизайнеров, если есть такая возможность. В общем же случае мы все отдаем предпочтение хорошим интерфейсам, даже если не всегда знаем, что делает их хорошими.
С помощью кода создаются интерфейсы. Но и сам код, в сочетании с IDE, — это интерфейс. Интерфейс, предназначенный для очень небольшой группы пользователей — наших коллег. Далее будем называть их «пользователями» — чтобы оставаться в пространстве проектирования пользовательского интерфейса.
Имея это в виду, рассмотрим такие примеры путей пользователя:
Можно уверенно предположить, что пользователь не сможет сразу открыть нужный участок кода. Это касается и собственных хобби-проектов: даже если функция написана вами, очень легко забыть, где она находится. Поэтому код должен быть таким, чтобы в нем было легко найти нужное.
Чтобы реализовать удобный поиск, понадобится некоторая поисковая оптимизация — здесь-то нам и приходят на выручку осмысленные имена переменных. Если пользователь не может найти функцию, перемещаясь по стеку вызовов из известной точки, он может запустить поиск по ключевым словам. Однако нельзя включать в имена слишком много ключевых слов. При поиске по коду ищется единственная точка входа, откуда можно продолжить работу дальше. Поэтому пользователю нужно помочь попасть в конкретное место, а если перестараться с ключевыми словами, будет слишком много бесполезных результатов поиска.
Если пользователь имеет возможность сразу убедиться, что на конкретном уровне логики всё верно, он может забыть предыдущие слои абстракции и освободить ум для последующих.
Искать можно и с помощью автодополнения: если есть общее представление о том, какую функцию нужно вызвать или какое перечисление использовать, можно начать набирать предполагаемое имя, а затем выбрать подходящий вариант из списка автодополнения. Если функция предназначена только для определенных случаев или в ее реализацию нужно внимательно вчитываться из-за особенностей использования, на это можно указать, дав название подлиннее: прокручивая список автодополнения, пользователь будет скорее избегать того, что выглядит сложно — если, конечно, он не уверен, что делает.
Поэтому короткие обычные имена с большей вероятностью будут восприниматься как варианты по умолчанию, подходящие для «случайных» пользователей. В функциях с такими именами не должно быть сюрпризов: нельзя вставлять сеттеры в функции, которые выглядят, как простые геттеры, — по той же причине, по которой кнопка «Просмотр» в интерфейсе не должна изменять пользовательские данные.
В обращенном к клиенту интерфейсе привычные функции, такие как пауза, обходятся практически без текста. По мере усложнения функциональности названия удлиняются, что заставляет пользователей притормозить и задуматься. Снимок экрана — Pandora
Пользователи хотят находить нужную информацию быстро. В большинстве случаев на компиляцию требуется значительное время, причем в запущенном приложении придется вручную проверить множество различных пограничных случаев. При возможности наши пользователи предпочтут прочитать код и понять, как он себя ведет, а не расставлять точки останова и запускать код.
Чтобы обойтись без запуска кода, должны выполняться два условия:
Последовательное чтение файла или метода выполняется за линейное время. Но если пользователь может переходить вверх и вниз по стекам вызовов — это уже поиск по дереву, а если иерархия хорошо сбалансирована, это действие выполняется за логарифмическое время. В интерфейсах, безусловно, есть место и спискам, однако следует тщательно продумывать, должно ли быть в каком-то контексте больше двух-трех вызовов методов.
По коротким меню иерархическая навигация выполняется намного быстрее. В «длинном» меню справа — всего 11 строк. Как часто в коде методов мы укладываемся в это число? Снимок экрана — Pandora
Стратегии для второго условия у разных пользователей разные. В ситуациях с низким риском достаточным доказательством будут комментарии или имена методов. В более рискованных, сложных областях, а также когда код перегружен неактуальными комментариями, последние скорее всего будут игнорироваться. Иногда даже имена методов и переменных будут вызывать сомнение. В таких случаях пользователь должен прочитать намного больше кода и держать в голове более обширную модель логики. Здесь также поможет ограничение контекста небольшими областями, на которых легко удержать внимание. Если пользователь имеет возможность сразу убедиться, что на конкретном уровне логики всё верно, он может забыть предыдущие слои абстракции и освободить ум для последующих.
В таком режиме работы большее значение начинают иметь отдельные лексемы. Например, булевский флаг
легко понять в отрыве от остального кода, однако для этого требуется объединить в уме две разных лексемы. Если же использовать
то значение флага можно понять с ходу: в этом случае не нужно читать имя переменной, чтобы выяснить, что она имеет отношение к видимости.¹ Аналогичные подходы мы видели в проектировании ориентированных на клиента интерфейсов. За последние десятилетия кнопки подтверждения действий «ОК» и «Отмена» превратились в более описательные элементы интерфейса: «Сохранить» и «Отменить», «Отправить» и «Продолжить редактирование» и т. д., — чтобы понять, что будет выполнено, пользователю достаточно взглянуть на предложенные варианты, не считывая весь контекст полностью.
Строка «Offline Mode» в примере сверху указывает, что приложение работает в автономном режиме. Переключатель в примере ниже имеет тот же смысл, но чтобы понять его, нужно взглянуть на контекст. Снимок экрана — Pandora
Подтвердить ожидаемое поведение кода также помогают модульные тесты: они выступают как комментарии — которым, однако, можно доверять в большей степени, поскольку они лучше сохраняют актуальность. Правда, для них тоже нужно выполнять сборку. Но в случае хорошо налаженного CI-конвейера тесты запускаются регулярно, поэтому при внесении изменений в существующий код этот шаг можно пропустить.
В теории, безопасность следует из достаточного понимания: как только наш пользователь поймет поведение кода, он сможет безопасно вносить правки. На практике же приходится учитывать, что разработчики — обычные люди: наш мозг использует те же уловки и так же ленится. Поэтому чем меньше сил нужно потратить на понимание кода, тем безопаснее наши действия.
Читабельный код должен передавать бо́льшую часть проверок на ошибки компьютеру. Один из способов это осуществить — отладочные проверки «assert», однако и для них требуются сборка и запуск. Что еще хуже, если пользователь забыл о пограничных случаях, «assert» не поможет. Модульные тесты с проверкой часто забываемых пограничных случаев могут справляться лучше, но как только пользователь внес изменения, придется ждать прогона тестов.
Резюмируя: читабельный код должен быть удобен в использовании. И — как побочный эффект — он может выглядеть красиво.
Чтобы ускорить цикл разработки, мы используем функцию проверок на ошибки, встроенную в компилятор. Обычно для таких случаев полная сборка не требуется, а ошибки отображаются в реальном времени. Как использовать эту возможность в своих интересах? Вообще говоря, нужно найти ситуации, когда проверки компилятора становятся очень строгими. Например, большинство компиляторов не смотрят, насколько исчерпывающе описан оператор «if», но тщательно проверяют «switch» на пропущенные условия. Если пользователь пытается добавить или изменить условие, будет безопаснее, если все предыдущие аналогичные операторы были исчерпывающими. И в момент изменения условия «case» компилятор пометит все остальные условия, которые необходимо проверить.
Еще одна распространенная проблема читабельности — использование примитивов в условных выражениях. Особенно остро эта проблема проявляется, когда приложение анализирует JSON, ведь так и хочется понаставить операторов «if» вокруг строкового или целочисленного равенства. Это не только повышает вероятность опечаток, но и усложняет пользователям задачу определения возможных значений. При проверке пограничных случаев есть большая разница между тем, когда возможна любая строка, и когда — лишь два-три отдельных варианта. Даже если примитивы зафиксированы в константах, стоит один раз поспешить, стараясь закончить проект в срок, — и появится произвольное значение. Но если применять специально созданные объекты или перечисления, компилятор блокирует недопустимые аргументы и дает конкретный список допустимых.
Точно так же, если некоторые комбинации булевских флагов недопустимы, следует заменить их на одно перечисление. Возьмем, к примеру, композицию, которая может быть в следующих состояниях: буферизируется, загружена полностью и воспроизводится. Если представить состояния загрузки и воспроизведения как два булевских флага
компилятор будет разрешать ввод недопустимых значений
А если использовать перечисление
то недопустимое состояние указать будет невозможно. В ориентированном на клиента интерфейсе по умолчанию должен быть запрет недопустимых комбинаций настроек. Но когда мы пишем код внутри приложения, мы часто забываем обеспечить себе такую же защиту.
Недопустимые комбинации заранее отключены; пользователям не нужно задумываться, какие конфигурации несовместимы. Снимок экрана — Apple
Следуя по рассмотренным пользовательским путям, мы пришли к тем же правилам, что и в начале. Но теперь у нас есть принцип, по которому их можно формулировать самостоятельно и изменять в соответствии с ситуацией. Для этого мы спрашиваем себя:
Примечание
Перевод статьи выполнен в Alconost.
Alconost занимается локализацией игр, приложений и сайтов на 70 языков. Переводчики-носители языка, лингвистическое тестирование, облачная платформа с API, непрерывная локализация, менеджеры проектов 24/7, любые форматы строковых ресурсов.
Мы также делаем рекламные и обучающие видеоролики — для сайтов, продающие, имиджевые, рекламные, обучающие, тизеры, эксплейнеры, трейлеры для Google Play и App Store.
10 способов сделать свой код более читаемым
Перевод статьи Джейсона МакКрири «10 practices for readable code».
Я занимаюсь программированием уже 20 лет. За это время я поработал с 17 командами и в ходе создания сотен проектов программировал на разных языках. Среди этих проектов были и простые сайты-блоги, и APIs с поддержкой 3 тыс. запросов в секунду, и топовые приложения для продаж товаров.
На основе своего опыта, а также прочитанных мною книг, я сумел определить, что в коде имеет самое больше значение: читаемость.
На первый взгляд, читаемость это понятие субъективное. Нечто, зависящее от языка, кодовой базы и команды. Но если копнуть глубже, мы увидим в коде основные элементы, делающие его читаемым.
Многие программисты чересчур близки к компьютерам. Для них важно только то, что код работает, а все остальное не имеет значения. Отсюда распространенные порывы удалить все «человеческие» элементы из нашей работы.
Последние несколько месяцев я потратил на то, чтобы выделить эти элементы в 10 подходов к написанию кода с фокусом на читаемости и уменьшении сложности. Я расписал их детально и приложил отрывки настоящего кода в BaseCode.
К сожалению, многие отбрасывают эти подходы как нечто тривиальное. Слишком базовое. Но я вас уверяю, в каждом кусочке плохого кода, который я встречал, эти подходы не применялись. И наоборот, в каждом хорошем коде можно проследить применение хотя бы одного из этих подходов (если не многих).
Форматирование
На форматирование идет так много энергии. Табы против пробелов. Олман против K&R. Но однажды вы достигнете понимания, что форматирование это не то, что имеет значение в программировании. Примите стандартный формат, примените его к кодовой базе и автоматизируйте. После этого вы сможете перенаправить свою энергию на написание самого кода.
Мертвый код
Все эти закомментированные блоки, неиспользуемые переменные и недостижимый код это гниль. Они прямо говорят читателю: «Мне плевать на этот код». Так и начинается цикл разрушения. Со временем этот мертвый код убьет вашу кодовую базу. Это классический случай теории разбитых окон.
Мертвый код нужно находить и уничтожать. И хотя это не должно быть вашим основным фокусом, руководствуйтесь принципом бойскаутов: «Оставь это в лучшем виде, чем оно было до тебя».
Вложенность кода
Основа практически всего кода это логика. Мы пишем код, чтобы принимать решения, производить итерации и вычисления. Часто это приводит к ветвлению циклов, что создает глубоко вложенные блоки кода. И хотя для компьютера не составляет труда понять этот код, человеку потребуется приложить значительные умственные усилия, чтобы его прочесть.
Распутывайте вложенный код, используя охранные выражения, ранний возврат или аспекты функционального программирования.
Использование объектов
Хотя у нас эра объектно-ориентированного программирования, у нас все еще есть одержимость элементарными типами. Мы обнаруживаем ее в длинных списках параметров, группах данных и пользовательских структурах массивов/словарей. Все это можно преобразовать в объекты. Это не только формализует структуру данных, но и предоставит дом для всей повторяющейся логики, которая сопутствует примитивным типам.
Большие блоки
Поскольку я не очень «дружу» с большими числами, просто скажу, что блоки кода могут достигать критической длины. Когда вы понимаете, что у вас есть большой блок кода, стоит заняться его перегруппированием и перепроектированием.
Этот простой процесс позволит вам определить контекст и уровень абстракции этого блока кода. Благодаря этому вы сможете правильно идентифицировать, что за что отвечает в этом коде и сделать рефакторинг, чтобы получить более читаемый и менее сложный блок.
Имена
Конечно, придумывать имена – сложное дело. Но только потому, что мы делаем его сложным. Есть небольшая уловка, хорошо работающая в отношении разных вещей в программировании, включая именование, – отсрочка. Не тормозите, пытаясь выдумать имя для чего-нибудь. Просто продолжайте программировать. Назовите переменную целым предложением, если нужно. И просто продолжайте писать код. Я гарантирую, что к тому времени, как вы закончите писать этот функционал, наилучшее имя для переменной всплывет в голове само.
Удаление комментариев
Эта простая практика для меня была оригинальной сменой правил игры. Именно это заставило меня сосредоточиться на читаемости.
Несмотря на все мои попытки объяснить этот пункт, всегда найдется кто-то, кто будет меня за это ненавидеть. У этих людей всегда есть на руках именно тот пример, где комментарий был абсолютно необходим.
Конечно, если телеметрическая система телескопа Хаббла должна взаимодействовать с устаревшим адаптером путем возврата 687 для неизвестных показаний, то, вероятно, потребуется коммуникация в виде комментария. Но что касается практически всего остального, вам стоит озадачиться и переписать код таким образом, чтобы он не нуждался в комментариях.
Разумные возвраты значений
Вы должны стараться возвращать более разумные значения. А для действительно исключительных случаев есть лучшие способы коммуникации, чем null.
Правило трех
Подумайте о математической последовательности чисел. Я называю число 2 и спрашиваю: «Какое следующее?» Возможно, это 3 или 4, но может быть и 1, и 2,1. На самом деле вы понятия не имеете. Поэтому я называю еще одно число последовательности – 4 (теперь имеем 2, 4) и спрашиваю: «Какое следующее?» Вероятно, это 6 или 8, или 16. Опять же, несмотря на нашу растущую уверенность, на самом деле мы не знаем. Я выдаю еще одно число из серии, теперь это 2, 4, 16, и спрашиваю: «Какое следующее?» Имея три точки данных, мозг программиста видит последовательность квадратов и определяет, что следующее число – 256. Это правило трех.
Данный пример и без привлечения кода показывает, что мы не должны сразу предполагать абстракцию или дизайн. С помощью отсрочки правило трех противостоит необходимости борьбы с дубликатами. Отсрочка позволяет собрать больше данных для принятия решения на их основе. Говоря словами Сэнди Мец, «дублирование намного дешевле, чем неверная абстракция».
Симметрия
И последний подход. Имеющий отношение к практически поэтической стороне читаемости – симметрии. Из «Implementation Patterns» Кента Бека:
Симметрия в коде это когда одна и та же идея выражается одинаково везде, где бы ни была.
Это легче сказать, чем сделать. Симметрия воплощает творческую сторону программирования. Она лежит в основе многих других подходов: именования, структуры, объектов, шаблонов. Симметрия может варьироваться в зависимости от языка, кодовой базы, команды. Поэтому на достижение симметрии может уйти вся жизнь. Кроме всего прочего, как только вы начинаете стремиться к симметрии в своем коде, в нем появляются более чистые формы и он быстрее принимает свои очертания.