Comments

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

Но еще одна важная часть этого процесса — это комментарии в коде. Так же, как и в HTML и CSS, можно писать комментарии на вашем JavaScript коде, что будет проигнорировано браузером, и что существует только для того, чтобы давать подсказки вашим друзьям-разработчикам о том, как работает код (и лично вам, если вы вернетесь к коду спустя 6 месяцев и не сможете вспомнить, что вы делали). Комментарии очень полезны, и вы должны часто их использовать, особенно для больших приложений.

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

• Код без комментариев не оптимален.

• Слишком много комментариев (по одному на каждую строку кода, например) являются признаком плохо написанного кода.

• Комментарии должны объяснять: почему, а не что. Они могут дополнительно объяснять:

  как, когда код особенно сложен.

В JavaScript есть два типа комментариев: однострочный комментарий и многострочный комментарий. Синтаксис комментариев является таким же, как в C++ и во многих других языках:

// Комментарий, занимающий одну строку.


/* Комментарий, 
   занимающий несколько строк.
*/
 
/* Нельзя вкладывать /* комментарий в комментарий */ SyntaxError */

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

var a = 42;        // 42 - смысл жизни

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

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

 var a = 42;

Источники:

1. You don't know js

2. MDN