¿Cuál es la forma correcta de comentarios de código en JavaScript

Question

¿Cuál es la forma correcta de comentarios de código en Javascript? ¿Es la misma sintaxis que en Java? Y que las herramientas de realidad se aprovecharían de estos comentarios:

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

He encontrado nueva ReSharper 6 (escribo JS en VisualStudio 2010) ofrece los mismos comentarios que en C#, pero sólo dentro del cuerpo de funciones, algo así como /// <param name="overlayElement"></param> . Los comentarios del código JS no están resaltados como tales por ReSharper.

¿Cuál es la mejor manera de ir ...?

Answer 1

usando // es mejor que /* */ porque luego puede utilizar este último para eliminar un bloque completo que contiene otros comentarios. Sin embargo, si desea utilizar una herramienta de generación automática de documentación, debe usar comentarios similares al estilo javaDoc.

Este es un ejemplo que trabajaría con DOC YUI (mejor) 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 
*/ 

Answer 2

buena práctica es utilizar // en lugar de /* */

La razón de esto es porque si usted tiene */ en cualquier parte del comentario (suponiendo que no tiene intención de poner fin a todo), que terminaría el comentario. Esto sucede incluso si */ está en una cadena. es decir, "*/" < --- esto terminaría el comentario y probablemente le daría un error de sintaxis.

note // termina en un salto de línea por lo que necesitaría // para cada línea de comentario.

Answer 3

Un buen ejemplo son los comentarios basados ​​en Java, que también se usan con JSDoc. Puede encontrar ejemplos aquí: http://code.google.com/p/jsdoc-toolkit/wiki/FAQ

Para agregar formularios simples como comentarios, el // sigue siendo una buena manera de comentar su código. Pero para generar documentación, me gustaría ir con la sintaxis de JSDoc. Lo he usado en el pasado y funciona bastante bien.