Читаемый код — это поддерживаемый код

В этом посте я расскажу о некоторых правилах, которые вы можете применить для улучшения своего кода. Все примеры кода написаны на Javascript.

Я считаю, что удобочитаемый код — это код, который можно поддерживать.
Моя цель как разработчика — писать качественный код. Каждый разработчик в команде, независимо от уровня его навыков, должен уметь понимать код, читая его. Это помогает молодым разработчикам быть более уверенными в написании кода.

Удалить ненужные комментарии кода

Конечно, некоторый код может быть очень сложным. Я это знаю и видел много раз. Здесь я бы добавил соответствующую документацию и комментарии к коду. Не поймите меня неправильно. Я не фанат комментариев к коду или в Javascript JSdoc. Или, по крайней мере, пока они мне не нужны.

Мне не нужны комментарии, чтобы прочитать, что эта функция берет X массивов и объединяет их вместе в новый массив.

Добавление JSdoc в этот код не улучшает читаемость. Я ожидаю, что члены моей команды знают, что такое оператор спреда. А если нет, то они должны спросить об этом во время код-ревью.

И давайте не будем забывать прокомментированные блоки кода. Только одно решение для этого: УДАЛИТЬ ЭТОТ КОД. В Git есть замечательная функция проверки старого кода, так зачем оставлять ее в комментариях?

Пожалуйста, перестаньте превращать свою кодовую базу в свалку.

Сосредоточьтесь на именовании

Если вы посмотрите на имя mergeArrays, должно быть очень ясно, что эта функция объединяет X массивов в новый.

Я знаю, что называть вещи трудно. И чем сложнее функция, тем сложнее будет именование... Я использую правило, чтобы облегчить себе именование. Вот как я это делаю.

Представьте себе функцию, которая объединяет 2 массива чисел и генерирует новый уникальный список чисел. Как бы вы назвали это? Что-то вроде этого?

Название не так уж плохо, потому что оно делает то, что говорит. Проблема в том, что функция делает 2 вещи. Чем больше делает функция, тем сложнее ей назвать. Извлечение его в 2 отдельные функции сделает его намного проще и в то же время более пригодным для повторного использования.

Конечно, легко создать красивый однострочный код без вызова новой функции. Но иногда однострочники не так читабельны.

Операторы if

Я не мог найти название для этой проблемы… Смотрите! Давать имена сложно...
Но я часто такое вижу.

Делая это, вы создаете удобочитаемый фрагмент кода, который выглядит как английское предложение.

Если параметры содержат значение, то…

Ранний выход

Есть дюжина способов назвать этот принцип, но я выбрал название «Ранний выход». Итак, позвольте мне показать вам кусок кода. Я уверен, что вы видели что-то подобное раньше.

Здесь мы пытаемся проверить, не является ли объект event ложным и доступно ли свойство target. Теперь проблема в том, что мы уже используем 2 оператора if.

Давайте посмотрим, как вы могли бы сделать «ранний выход» здесь.

Применяя здесь «ранний выход», вы проверяете, не являются ли event и event.target ложными. Сразу видно, что мы уверены, что event.target не ложно. Также ясно, что никакой другой код не выполняется, если это утверждение ложно.

Назначение деструктурирования

В Javascript мы можем деструктурировать объекты и массивы.
Согласно документации, найденной на developer.mozilla.org, the destructuring assignment syntax is a JavaScript expression that makes it possible to unpack values from arrays, or properties from objects, into distinct variables.

Некоторые примеры кода

Проблема с деструктурированием заключается в том, что иногда оно создает плохое имя для свойства. Прекрасным примером является выборка данных из API и получение объекта ответа, который имеет свойство данных.

В этом примере кода показано, что вы извлекаете органайзер с идентификатором 1. У объекта органайзера есть имя, и вы деструктурируете его. В этом нет ничего плохого.
Этот код работает и в порядке. Но почему имя все еще name? Будет ли это единственным свойством name во всей области видимости? И от какого объекта опять это имя?

Чтобы избежать этих вопросов, переименуйте свойство.

Этот код становится более читаемым. Все будут знать, что переменная — это имя органайзера.

Правило бойскаута

Вы когда-нибудь слышали фразу: «Оставить лучше, чем было»?
Ну, это именно то, что гласит правило бойскаутов. Оставьте код лучше, чем вы его нашли. Вы нашли запах кода? Рефакторинг! Вы нашли неиспользуемую переменную? Убери это!

Мне нравится сравнивать это с уборкой комнаты. Давайте представим, что все в вашем доме оставляют посуду на раковине, весь мусор выносят в прихожую, а все белье оставляют в ванной. Но каждое воскресенье нужно убираться во всем доме, и на это уходит более 4 часов. Вы бы хотели это?

Я уверен, что нет. Так что, если все немедленно уберут маленькие части дома, в воскресенье работы будет меньше.

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

Стиль кода

Последний, но тем не менее важный. Определите стиль кода в своей команде.
Мне все равно, предпочитаете ли вы одинарные или двойные кавычки, пробелы или табуляции, запятую в конце или без запятой. Выберите 1 стиль и придерживайтесь его. Вы можете сделать это с помощью линтера и/или красивее.

Существует так много инструментов, которые можно использовать для решения такого рода проблем. Мой любимый хук перед фиксацией с использованием Husky. У Prettier также есть страница в документации о хуках перед фиксацией.

Этот хук перед фиксацией всегда запускает сконфигурированную команду перед каждой фиксацией. Если настроить его правильно, он работает красивее и применяет все правила ко всем файлам. Это гарантирует, что команда всегда использует один и тот же стиль кода без какого-либо плохого кода.

Вывод

Я знаю, что некоторые правила очевидны, а другие нет. Но как штатный разработчик я работаю над разными кодовыми базами. Важность этих правил становится очевидной только в больших кодовых базах. Но это не значит, что вы не должны применять его в своих небольших проектах. Улучшение качества кода поможет вам работать более эффективно в небольших проектах. Это также поможет вашей команде прочитать код и утвердить ваши запросы на вытягивание. Как я уже сказал, читабельный код легче поддерживать, но он также имеет гораздо больше преимуществ.

Если вы хотите узнать больше о чистом коде, прочтите Чистый код Роберта Мартина. Если вам нравится мой контент, не забудьте подписаться на меня в Твиттере, где я публикую все ссылки на блоги, которые я публикую. Я стараюсь выпускать 1 каждую неделю на разные темы.