Стиль кода

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

Синтаксис

Шпаргалка с правилами синтаксиса:

Пробелов может быть и больше. Главное, не меньше

Разберём основные моменты.

Фигурные скобки

Пишутся на той же строке, так называемый «египетский» стиль. Перед скобкой — пробел.

Если у вас уже есть опыт в разработке и вы привыкли делать скобку на отдельной строке — это тоже вариант. В конце концов, решать вам. Но в основных JavaScript-фреймворках (jQuery, Dojo, Google Closure Library, Mootools, Ext.JS, YUI…) стиль именно такой.

Если условие и код достаточно короткие, например if (cond) return null;, то запись в одну строку вполне читаема… Но, как правило, отдельная строка всё равно воспринимается лучше.

Отступы

Отступы нужны двух типов:

• Горизонтальный, при вложенности — два(или четыре) пробела.

  Как правило, используются именно пробелы, т.к. они позволяют сделать более гибкие «конфигурации отступов», чем символ «Tab».

  Например:
  

  function removeClass(obj, cls) {
    var targetObj = obj,
        targetClass = cls,         // <-- пробельный отступ выравнен!
        className = obj.className; // <--
    ...
  }
  

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

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

  Используется, чтобы разделить логические блоки внутри одной функции. В примере ниже разделены функция pow, получение данных x,n и их обработка if.

  function pow(..) {
    ..
  }
             // <--
  x = ...
  n = ...
             // <--
  if (n <= 1) {
    ...
  }
  ..
  

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

Точка с запятой

Точка с запятой ставится везде, включая динамическое объявление функции:

var func = function(a) {
  alert(a);
}; // <--

Есть языки, в которых точка с запятой не обязательна, и её там никто не ставит. В JavaScript она тоже не обязательна, но ставить нужно. В чём же разница?

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

function pow(x,n) 
{
  var result=x;  
  for(var i=1;i<n;i++) {result*=x;}       
  return result;
}

x=prompt("x?",'')
n=prompt("n?",'')
if (n<=1) 
{
  alert('Степень '+n+'не поддерживается, введите целую степень, большую 1');
} 
else 
{
  alert(pow(x,3))
}

Именование

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

• Имя переменной — существительное.
• Имя функции — глагол, или начинается с глаголом. Бывает, что имена для краткости делают существительными, но глаголы понятнее.

Для имён используется английский язык (не транслит) и верблюжья нотация.

Более подробно — читайте про имена функций и имена переменных.

Уровни вложенности

Уровней вложенности должно быть немного.

Например, проверки в циклах лучше делать через «continue», чтобы не было дополнительного уровня if(..) { ... }:

Вместо:

for (var i=0; i<10; i++) {
  if (i подходит) {
    ... // <- уровень вложенности 2
  }
}

Используйте:

for (var i=0; i<10; i++) {
  if (i *!*не*/!* подходит) *!*continue*/!*;
  ...  // <- уровень вложенности 1
}

Аналогичная ситуация — с if/else и return. Следующие две конструкции идентичны.

Первая:

function isEven(n) { // проверка чётности
  if (n % 2 == 0) {
    return true;
*!*
  } else { 
    return false;
  }
*/!*
}

Вторая:

function isEven(n) { // проверка чётности
  if (n % 2 == 0) {
    return true;
  }
 
*!*
  return false; 
*/!*
}

Если в блоке if идёт return, то else за ним не нужен.

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

В случае с функцией isEven можно было бы поступить и проще:

function isEven(n) { // проверка чётности
  return n % 2 == 0; 
}

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

function isEven(n) { // проверка чётности
  return !(n % 2); 
}

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

Функции = Комментарии

Функции должны быть небольшими. Если функция большая — желательно разбить её на несколько.

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

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

Сравните, например, две функции showPrimes(n) для вывода простых чисел до n.

Первый вариант:

function showPrimes(n) {
  nextPrime: 
  for (var i=2; i<n; i++) {

    for (var j=2; j<i; j++) {
      if ( i % j == 0) continue nextPrime;
    }
    
    alert(i);  // простое
  }
}

Второй вариант, вынесена подфункция isPrime(n) для проверки на простоту:

function showPrimes(n) {
  
  for (var i=2; i<n; i++) {
    *!*if (!isPrime(i)) continue;*/!*
     
    alert(i);  // простое         
  }
}

function isPrime(n) {
  for (var i=2; i<n; i++) {
    if ( n % i == 0) return false;
  }
  return true;
}

Второй вариант проще и понятнее, не правда ли? Вместо участка кода мы видим действие, которое там совершается (проверка isPrime).

Функции — под кодом

Есть два способа расположить функции, необходимые для выполнения кода.

1. Функции над кодом, который их использует:

   // *!*объявить функции*/!*
   function createElement() {
     ...
   }
   
   function setHandler(elem) {
     ...
   }
   
   function walkAround() {
     ...
   }
   
   // *!*код, использующий функции*/!*
   var elem = createElement();
   setHandler(elem);
   walkAround();
   

2. Сначала код, а функции внизу:
   

   // *!*код, использующий функции*/!*
   var elem = createElement();
   setHandler(elem);
   walkAround();
   
   // --- *!*функции*/!* ---
   
   function createElement() {
     ...
   }
   
   function setHandler(elem) {
     ...
   }
   
   function walkAround() {
     ...
   }
   

…На самом деле существует еще «третий» стиль, при котором функции хаотично разбросаны по коду, но мы здесь его не рассматриваем.

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

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

У первого способа, впрочем, есть то преимущество, что на момент чтения мы уже знаем, какие функции существуют.

Таким образом, если над названиями функций никто не думает — может быть, это будет лучшим выбором . Попробуйте оба варианта, но по практике автора предпочтителен всё же второй.

Комментарии

В коде нужны комментарии четырёх основных типов.

1. Справочный комментарий перед функцией — о том, что именно она делает, какие параметры принимает и что возвращает.

   Для таких комментариев существует синтаксис JSDoc.

   /**
    * Возвращает x в степени n, только для натуральных n
    *
    * @param {number} x Число для возведения в степень.
    * @param {number} n Показатель степени, натуральное число.
    * @return {number} x в степени n.
    */
   function pow(x, n) {
     ...
   }
   

   Такие комментарии обрабатываются многими редакторами, например Aptana и редакторами от JetBrains. Они учитывают их при автодополнении.

2. Краткий комментарий, что именно происходит в данном блоке кода. В хорошем коде он нужен редко, и так всё понятно из переменных, имён функций.
3. Почему это именно так?

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

   Гораздо важнее — то, чего вы не видите.

   • Есть несколько способов решения задачи. Почему выбран именно этот?

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

   • Какие неочевидные возможности обеспечивает этот код?

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

4. Архитектурный комментарий — «как оно, вообще, устроено». Применённые технологии, поток взаимодействия. Для этого, в частности, используется UML, но можно и без него. Главное — чтобы понятно.

Итого

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

Следуя (или не следуя) им, необходимо помнить, что любые советы по стилю хороши лишь тогда, когда делают код читаемее, понятнее.