Лучшие практики JavaScript: именование, стиль и комментарии

Лучшие практики JavaScript: именование, стиль и комментарии

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

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

Простые и понятные имена переменных, функций и классов.

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

Это означает, что не должно быть имён типа b, также как и не должно быть излишне громоздкое и перенасыщенное посторонними словами вроде soVeryUselessLongBirthdayVariable. Было бы уместно назвать его просто birthday.

Кроме этого, лучше избегать комбинирования имени с функциональностью в названии переменной. Например, если мы хотим написать функцию по проверке достижения пользователем совершеннолетия, мы должны назвать её чем-то вроде isAdult(), а не isOverEighteen().
Это также имеет больше смысла, так как не в каждом месте возраст 18 лет является возрастом совершеннолетия.

Мы также можем рассмотреть венгерскую нотацию для именования переменных и функций. Нотация объединяет в себе тип возврата, и имя в одно название. Поскольку JavaScript-функция не имеет определённого типа возврата, мы можем добавить префикс типа для функции.
Например, если переменная возвращает булево значение с помощью функции isAdult(), мы можем написать bIAdult() с указанием b, что она является булевым значением.

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

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

Избегайте частого использования глобальных переменных и функций.

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

К счастью, начиная с ES6, JavaScript имеет несколько возможностей для решения этой проблемы. Одна из них - использование модулей. С модулями, только то, что мы явно экспортируем, доступно для использования другими модулями.
Также должен быть включен строгий режим JavaScript, чтобы предотвратить случайное объявление глобальных переменных. При строгом режиме что-то вроде x = 1 приведет к ошибке без ключевых слов var, let или const перед ней.

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

Например, с var, если мы пишем следующий код:

if (true) {
  var x = 1;
}
console.log(x);

Выполнив этот пример, вызвав console.log, мы увидим результат 1. Это всё из-за того, что объявление переменной через var применяется к глобальной области видимости.

В другом же случае, если мы используем let вместо var:

if (true) {
  let x = 1;
}
console.log(x);

В результате мы получаем ошибку 'Uncaught ReferenceError: x is not defined'.
Как мы видим, мы не можем обращаться к переменным, которые доступны только в ограниченной области видимости (в данном случае, области видимости функции).

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

Например, мы можем написать:

(function() {
  var x = 1;
})();
console.log(x);

И тут мы также мы получим ошибку 'Uncaught ReferenceError: x is not defined'. Функция, которая запускается сразу же после объявления, как показано выше, называется IIFE (Immediately Invoked Function Expression) "Функция немедленного вызова".
Если мы хотим вернуть что-то из этой функции другому коду, который у нас есть выше, мы можем просто вернуть данные следующим образом:

let foo = (function() {
  var x = 1;
  return {
    bar: 2
  }
})();
console.log(foo.bar);

Мы вернули объект со свойством bar и присвоили его переменной foo. И, в результате, мы должны получить 2 из вывода console.log.

Следуйте строгому стиль программирования.

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

Есть также такие инструменты, как Prettier, для последовательного форматирования кода посредством стиля кода нашего приложения.

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

Комментарий при необходимости

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

Простая функция, которая состоит из нескольких строк, наверное, не нуждается в больших пояснениях.

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

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

/*
  function foo(){
    return 1
  };  
// */

Таким образом, мы можем раскомментировать код, поставив слеш перед открывающим слешем в первой строке. И, чтобы раскомментировать код, достаточно:

//*
  function foo(){
    return 1
  };  
// */

Вышеуказанный код раскомментирован.

Многие текстовые редакторы также должны быть достаточно умны, чтобы автоматически распознавать и подсвечивать закомментированный и раскомментированный JavaScript-код.

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

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

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

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

И вот они все и есть, лучшие JavaScript практики по комментированию, именованию и стилю написания кода.