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

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

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

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

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

Ответ 1

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

Это пример, который будет работать с YUI DOC (лучший) http://developer.yahoo.com/yui/yuidoc/#start

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

Ответ 2

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

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

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

Ответ 3

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

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