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

Question

Как правильно писать комментарии к коду в Javascript - тот же синтаксис, что и в Java?И какие инструменты действительно воспользуются этими комментариями:

  /*
  * Add an element to the group
  * @param {Object}  overlayElement
  * @param {Object} [element2] optional element
  */ 

Я обнаружил, что новый Resharper 6 (я пишу JS в VisualStudio 2010) предлагает те же комментарии, что и в C #, но только внутри тела функций, что-то вроде/// <param name="overlayElement"></param> .Комментарии к коду JS не выделены как таковые ReSharper.

Каков наилучший способ ...?

Answer 1

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

Это пример, который будет работать с YUI DOC (лучший) https://yui.github.io/yuidoc/

/**
* This is a description
* @namespace My.Namespace
* @method myMethodName
* @param {String} some string
* @param {Object} some object
* @return {bool} some bool
*/

Answer 2

Хорошей практикой является использование // вместо /* */

Причина этого в том, что если у вас есть */ в любой части комментария (при условии, что вы еще не собираетесь заканчивать), это закончило бы комментарий.Это происходит, даже если */ в строке.т.е. "*/" <--- это завершит комментарий и, скорее всего, приведет к синтаксической ошибке. </p>

note // заканчивается на разрыве строки, поэтому вам потребуется // для каждой строки комментария.

Answer 3

Хороший пример - это комментирование на основе Java, которое также используется с JSDoc.Вы можете найти примеры здесь: http://code.google.com/p/jsdoc-toolkit/wiki/FAQ

Чтобы добавить простые комментарии в качестве комментариев, // все еще хороший способ комментировать ваш код.Но для создания документации я бы использовал синтаксис JSDoc.Я использовал его в прошлом, и он работает довольно хорошо.