Эта статья написана с точки зрения создания приложения Angular, но, вероятно, ее можно применить и в вашем контексте. Идеи будут передаваться независимо от фреймворка.

Введение

Мой коллега Йорис уже упоминал, что он перешел от использования VIM к использованию IDE. Теперь он рекомендует всем использовать IDE для написания Javascript. (Или, конечно, текстовый редактор, такой как VS Code, с правильными настройками и плагинами.) Он рассуждает так: хотя VIM помог ему писать код быстро, написание кода на самом деле не то, чем вы занимаетесь большую часть времени. . Это чтение кода: попытка понять, откуда взялась ошибка, или поиск, в какой класс вы могли бы добавить эту новую функцию. (То есть создание новых ошибок для последующего исправления.) IDE помогает быстро перемещаться по коду и выявлять проблемы на раннем этапе. Вы можете щелкнуть набор вызовов функций или посмотреть, где используется определенная переменная, или переименовать класс и обновить все его ссылки. Эти вещи помогут вам быть более продуктивными, так как это может занять много времени, если вы делаете это вручную.

Обычно мы работаем над проектами совместно. И все меняется постоянно. На самом деле изменение — единственная константа в разработке программного обеспечения. Вот некоторые из основных причин, по которым многие из нас используют Git. И при работе над такими проектами вы будете тратить много времени на чтение и интерпретацию кода, который там есть. Либо его создал кто-то из ваших коллег, либо это были вы. И, конечно же, сразу после написания этого алгоритма вы можете точно вспомнить, как он работал и почему. Но сможет ли коллега понять? Теперь не говорите мне ничего из того, что «я достаточно умен, чтобы понять этот код, и они должны быть такими же». Во-первых, ваши коллеги, вероятно, достаточно умны; тем не менее, небольшое объяснение сэкономит много времени. Во-вторых, вы забудете детали своей реализации через несколько месяцев, а возможно, и раньше. А затем, когда вам придется исправить ошибку в вашем алгоритме много месяцев спустя, вам придется мысленно перерешать многие исходные проблемы. Это напрасная трата времени, которую можно легко предотвратить, написав удобочитаемый и удобный для сопровождения код. Есть несколько приемов, которые помогут вам в этом, я назову их «Принципы создания поддерживаемого кода».

Принципы создания поддерживаемого кода

1. Будьте точны в своих соглашениях об именах. Устраните двусмысленность везде, где только можно.

Не сокращайте, если не совершенно ясно, что вы имеете в виду. т.е. логическое значение с именем «adminRightsRequired» допустимо, а «admRightsReq» — нет. Что такое «adm»? Означает ли «req» требуемый, запрошенный или еще что-то? Теперь вам нужно взглянуть на использование переменной, чтобы надеюсь правильно понять, что она означает. Я вижу, что это происходит слишком часто. Лучше быть явным, так как это экономит время.

Побочным эффектом дополнительной детализации будет то, что строки кода станут длиннее. ИМХО, это нормально. Установите правила линтинга, чтобы разрешить более часто используемых 80 символов в строке. Это связано с эпохой перфокарт для громкого крика. Кто сейчас не работает с экраном шириной хотя бы 1280 или даже 1920 пикселей? Этот компромисс кажется мне более чем стоящим.

Не беспокойтесь об увеличении файлов Javascript, которые будут загружены браузером при создании длинных имен переменных; если вы используете транспайлер, такой как Babel, или настройку, включающую, например, Webpack или Angular CLI, тогда код можно оптимизировать в процессе сборки.

2. Делайте классы и функции краткими

Классы и функции должны делать одно и делать это хорошо. Может быть очень заманчиво втиснуть все виды функциональности в один класс, пока он не раздуется до неузнаваемости, но это плохо для удобочитаемости и ремонтопригодности.

В нашем проекте у нас был класс FormHelpers, который помогал в некоторых небольших задачах, связанных с динамическими формами. Но по мере роста требований к форме в этот класс добавлялось все больше и больше функциональности. В конце концов, это был беспорядочный беспорядок из сотен строк кода. В итоге мы сохранили класс FormHelpers в первоначальном виде (scrollToFormControl, validateAllFormFields — два метода в нем), но выделили многие из его методов в отдельные классы FormStateManager и FormControlManager . Мы слишком долго ждали, прежде чем сделать это, что сделало это более болезненным, чем должно было быть.

То же самое может быть и с функциями. Простой пример может выглядеть так:

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

Здесь большая часть функций была извлечена в закрытые методы, такие как setSearchPlaceholder и getFiltersFromSessionStorage. Названия этих методов понятны и недвусмысленны. И никакие комментарии не нужны, чтобы объяснить, что мы делаем.

3. Не переусердствуйте с комментариями

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

Возьмем, к примеру, следующий код:

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

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

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

Здесь вы можете видеть, что комментарий добавляет ценность. Он не просто объясняет то, что уже было ясно видно при чтении кода. Он объясняет почему, а не что.

Я что-то упустил, или вы считаете, что я что-то исказил в статье? Пожалуйста, дайте мне знать в комментариях, каков ваш опыт создания поддерживаемого/читаемого кода.