Как правильно комментировать код JS?

Question

[Alexander Tartmin]

Когда смотрю код каких-то библиотек, часто натыкаюсь на комментарии такого вида

/**
                 * Описание функции и тд
                 * @param name
                 * @param defaultValue
                 * @returns {*}
                 */

Вот интерестно есть ли best-practice как правильно комментировать и что это за "параметры" (@param, @returns, @value) и где достать список всех доступных?

Comments

[1001001 111]

https://github.com/airbnb/javascript#comments

[Alexander Tartmin]

https://ru.wikipedia.org/wiki/JSDoc - таки стандарт описан

Answer 1

[copal]

/**
 * [param description]
 * @type {[type]}
 */
var param = null;

/**
 * [method description]
 * @param  {[type]} a [description]
 * @param  {[type]} b [description]
 * @param  {[type]} c [description]
 * @return {[type]}   [description]
 */
function method(a, b, c){
	return a + b + c;
}

Comments

[trevoga_su]

только newline после [param description] и [method description]

Answer 2

[evnuh]

@param - для генерации документации, blog.fusioncharts.com/2013/12/jsdoc-vs-yuidoc-vs-d...
Как комментировать - как докогенератору угодно и как вам самим угодно

Comments

[Alexander Tartmin]

Но всё же должен быть единый стандарт? Или в вэб-разработке никогда не будет стандартов? :D

[evnuh]

Alexander Tartmin: стандарт чего? ставить строчный или блочный комментарий? нет таких стандартов, best practices - для многострочных комментариев использовать блочный коммент /* */, для однострочных - строчный //.

[Alexander Tartmin]

evnuh: Вы написали что такого вида комментарии используют документогенераторы, они же должны следовать какому-то стандарту или каждый использует свою "разметку"? Просто если стандарт существует, было бы не плохо с ним ознакомится =)

[evnuh]

Alexander Tartmin: ссылку я вам за этим и привёт

[Stalker_RED]

Кстати, подобные комментарии используются и в других языках
https://ru.wikipedia.org/wiki/Javadoc
https://ru.wikipedia.org/wiki/PhpDocumentor

Answer 3

[Константин Китманов]

WebStorm хорошо понимает JsDoc.

P.S. Хорошо понимает — значит, строит интеллисенс согласно типам, указанным в JsDoc и помогает написать его правильно.

Comments

[Alexander Tartmin]

Да, это я уже заметил, по этому и заинтересовался темой правильного комментирования кода.

[Константин Китманов]

Alexander Tartmin: иногда, правда, у нее бывают свои (и меняющиеся) представления о том, как записывать сложные типы, например, массив объектов.

Answer 4

[trevoga_su]

я пишу в стиле php-doc.
стандартизировано и приятно читать