Сделайте свой код лучшей версией самого себя

Недавно я написал статью об использовании объектных литералов вместо операторов if/else и switch, чтобы сделать ваш код более читабельным, и мне было интересно прочитать ответы. Понятно, что читаемость кода для разных людей значит разное. На самом деле, это одна из самых субъективных вещей в написании кода, поэтому это такой спорный вопрос.

Итак, какие жесткие правила мы можем установить, чтобы всегда писать читаемый код?

Что такое читаемый код?

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

Каким правилам мы можем следовать, чтобы достичь этой утопии кода?

1. Единообразно форматируйте свой код

Начните с самого низкого результата, убедившись, что ваш код хорошо отформатирован. Два пробела или четыре? Точки с запятой или нет? Одиночные или двойные кавычки? Это абсолютно не имеет значения, если оно последовательное. Лучшее в форматировании кода - это то, что его можно легко применить с помощью анализатора кода, так что любое непоследовательное форматирование может быть мгновенно выявлено и исправлено.

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

2. Придумайте соглашения о кодировании и придерживайтесь их.

Соглашения о кодировании на самом деле являются расширением форматирования, но больше касаются шаблонов и стилей кодирования. Некоторыми примерами соглашений о кодировании может быть порядок импорта в файле, независимо от того, используете ли вы троичные или нет, или используете ли if/else и switch или объектные литералы.

Опять же, все это субъективно и приведет к разделению мнений, но ключевым моментом является последовательность. Независимо от того, любите вы или ненавидите троичные, если вся кодовая база единообразна в том, как она их использует, ваша когнитивная нагрузка будет снижена, и вы сможете быстро взглянуть на фрагмент кода и понять, что происходит, потому что вы знаете Что ожидать.

3. Всегда записывайте код с наименьшим общим знаменателем.

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

При этом нет причин избегать использования наиболее подходящего синтаксиса - даже если он может быть немного неясным. Например, не все будут знать о yield в JavaScript, но если это подходящий инструмент для работы, тогда используйте его. Надеюсь, любой, кто столкнется с этим и не понимает синтаксиса, приложит усилия, чтобы узнать об этом. Фактически, именно так я часто узнаю о новой концепции или синтаксисе.

Ключевым моментом здесь является то, что концептуально он должен быть достаточно простым, чтобы каждый мог ему следовать. Это означает, что ваш код будет красивым и читабельным, а в качестве бонуса он заставит вас серьезно задуматься о том, делаете ли вы что-то наиболее логичным способом. "Держать его просто глупо"!

4. Самый короткий код - не всегда самый читаемый

Не делайте ошибки, приравнивая меньше кода к лучшей читаемости. Наступает момент, когда более сжатый код может фактически начать становиться менее понятным. Прочтите Code Golf on Stack Exchange, и вы поймете, что я имею в виду!

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

5. Если ничего не помогает, оставьте комментарий

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

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

Простое правило - комментировать почему, а не что. Если вам нужно прибегнуть к комментариям, чтобы объяснить, что делает ваш код, то он, вероятно, не очень удобочитаем.

Заключение

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

Если мы все сможем запомнить эти правила, тогда мы сможем достичь утопии читаемого кода!

Спасибо за чтение. Я хотел бы услышать о любых других правилах, которым вы следуете, чтобы ваш код был читабельным. Дай мне знать в комментариях!