Последние пять лет я постоянно пытался улучшить свои навыки программирования, и одним из них было изучение и следование наиболее рекомендуемым стилям программирования.
Это руководство призвано помочь вам писать последовательный и элегантный код и включает в себя несколько советов по улучшению читаемости и удобства сопровождения кода. Он основан на наиболее популярных в сообществе принципах, но в него внесены некоторые изменения, чтобы он лучше соответствовал моим предпочтениям.
Стоит отметить, что я являюсь полноценным разработчиком JavaScript, и все мои заметки относятся к моему технологическому стеку (MEVN) и могут быть неприменимы к другим стекам.

Общие правила

Избегайте дублирования кода

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

Рассмотрите возможность слабой связи

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

Декларация

Прежде всего, не забывайте постоянно объявлять переменные.
Используйте ключевое слово const, если переменная не подлежит переназначению. Однако вы все равно можете использовать const для переменных, которые являются объектами или массивами, даже если вы планируете переназначить их вложенные элементы.
Обратите внимание, что модули и константные переменные всегда требуются, используя ключевое слово const.
Используйте ключевое слово let, если вы не можете использовать const, и используйте ключевое слово var только в том случае, если вам нужна поддержка старых браузеров.

Функции

Функции должны быть ограничены следующим:

• Четыре переменные
• Четыре параметра
• Тридцать строк кода (без учета комментариев)
• Четыре ветки (if-else, while, for, or-and, switch-case)

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

Струны

Используйте одинарные кавычки ' (а не двойные кавычки ") для обычных строковых литералов, но для строк со встроенными переменными/выражениями, многострочных строк и строк, содержащих символы одинарных кавычек, используйте шаблонные литералы.

Именование

Очень важно соблюдать единообразие при именовании переменных. Это означает, что если переменные на разных страницах отвечают за одни и те же данные, они должны иметь одно и то же имя.

Имена переменных, функций, методов и параметров должны быть понятными, то есть каждый должен иметь возможность узнать (или хотя бы сделать предположение) о содержащихся в них данных, просто взглянув на их имена.

Постоянные переменные должны быть написаны заглавными буквами, а слова разделяться подчеркиванием. Функции, переменные и методы должны следовать синтаксису CamelCase, а классы и идентификаторы CSS — синтаксису kebab-Case.

Комментарии

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

Размещайте комментарии после однострочных кодов, если длина строки не превышает 150 символов. В таких случаях и для многострочных кодов комментарии помещайте вверху.

Что касается операторов if, комментарии следует размещать после условных операторов.

if (conditionIsTrue) { // Put your comment here
    doSomeThing();
} else { // Put your comment here
    doSomethingElse();
}

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

if (conditionIsTrue) { /*
        Put your comment here
        Put your comment here
    */
    doSomeThing();
}

functionName(parameter), /*
    Put your comment here
    Put your comment here
*/

Описательные комментарии к функциям

Поместите комментарии поверх функций, заключенных в /** */.

• Опишите параметры, используя @param {type} описание переменнойName.
• Если параметр может принимать более одного типа переменной, используйте @param {type1 | type2} описание переменной.
• Если параметр не является обязательным и может отсутствовать, используйте описание @param {type} [variableName].
• Если параметр имеет значение по умолчанию (он должен быть необязательным, чтобы действительно иметь значение по умолчанию), используйте описание @param {type} [variableName="value"].
• Опишите вывод функции, используя описание @returns {type}.

/**
 * Describing the function here
 * @param {type} normalVariable A normal variable
 * @param {type1 | type2} multiTypeVariable A variable with multiple expected types
 * @param {type} [variableWithDefaultValue="value"] An optional variable that has a default value in case of being absent when calling the function 
 * @param {type} [optionalVariable] An optional variable
 * @returns {type} description
*/
const functionName = (normalVariable, multiTypeVariable, variableWithDefaultValue, optionalVariable) => {
    doSomeThing();
}

Что касается серверных функций с параметрами req и res, то параметры запроса описывать нет необходимости; описывайте ответ только с помощью описания @returns.

/**
 * Describing the function here
 * @returns description
 */
functionName = (req, res) => {
    doSomeThing();
}

Как правило, нет необходимости описывать параметры req, res, next, to и from.

В файлах HTML используйте для разделения различных частей кода; следовательно, пользователь может легко идентифицировать каждую часть.

Если вы пишете комментарии в середине строки кода, используйте /* */.

const calc_result = (firstNumber * secondNumber)/* Explain the reason for the multiplication */   thirdNumber;

Отступ

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

Заказ

• Упорядочите переменные схем mongoose и Vue Reactive State компонентов в алфавитном порядке, но в остальное время упорядочивайте строки от самых коротких к самым длинным.
• Упорядочите методы маршрута в порядке размещения, получения, публикации и удаления, при этом каждый из них расположен в алфавитном порядке, а все маршруты должны быть сгруппированы на основе их URL-адресов.

Заворачивать

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

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

Фото на обложке: фото Луиса Гомеса из Pexels