documentacion - documentar codigo javascript

¿JavaScript tiene un estándar para comentar funciones?

Question

Actualmente estoy escribiendo un código JavaScript del lado del cliente y me pregunto cómo comentar mis funciones.

Vengo de un entorno de C #, donde hay un estilo de comentario oficialmente recomendado documentado por Microsoft que sigo, que permite que el compilador y otras herramientas generen automáticamente la documentación.

Del mismo modo, el estilo PHPDoc de PHP es omnipresente y se está convirtiendo en un estándar oficial recomendado por PHP-FIG .

¿De manera similar, JavaScript tiene una cadena de herramientas universalmente aceptada, estándar o un conjunto de mejores prácticas que puedo aplicar al comentar mis funciones?

Answer 1

Puede usar el estilo jsdoc que le permitirá generar documentación más tarde

al igual que

/**
 * Adds two numbers
 * @param {Number} a 
 * @param {Number} b
 * @return {Number} sum
 */
 function sum(a,b) { 
   return a + b;
 }

EDITAR: Si está usando AngularJS, puede referirse a http://google.github.io/styleguide/angularjs-google-style.html

Answer 2

El estándar al que estoy acostumbrado es JSDoc: https://github.com/jsdoc3/jsdoc

Tiene un estilo similar a javadoc si estás familiarizado con eso.

Answer 3

Tenga en cuenta que las respuestas anteriores que sugieren el estilo JSDoc le dan una gran ventaja: puede generar documentos a partir de ellas. Eso es extremadamente valioso, especialmente a medida que su proyecto se amplía. Si no está interesado en JSDoc, o si busca consejos generales sobre comentarios, continúe leyendo.

Si ya tiene un método de documentación que funciona para usted, quédese con él. Si te gustan los bloques de comentarios grandes al comienzo de las funciones que explican todo de antemano, genial. Si desea insertar comentarios específicos en líneas específicas, quédese con eso en su lugar.

Otra cosa a considerar es la cultura: si se trata de un proyecto de trabajo, asegúrese de que la documentación del código esté en línea con lo que ha producido su equipo. Igual de importante, asegúrese de que su código esté en línea con los estándares del equipo también.

Pensamiento final: sé consistente. Un conjunto de reglas sobre cómo documentar, incluso si es solo para usted, hará que sus comentarios sean más fáciles de leer, escribir y comprender más adelante. Sabrá dónde buscarlos y qué le dirán.

Answer 4

Bueno, hay muchas maneras de agregar comentarios en javascript; Aquí está mi recomendación / mejores prácticas .

usar // es mejor que /* */ porque entonces puedes usar este último para eliminar un bloque completo que contenga 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 funcionaría con YUI DOC (el mejor) http://developer.yahoo.com/yui/yuidoc/#start

/**
* This is a description
* @namespace My.Namespace
* @method myMethodName
* @param {String} str - some string
* @param {Object} obj - some object
* @param {requestCallback} callback - The callback that handles the response.
* @return {bool} some bool
*/
    function SampleFunction (str, obj, callback) {
         var isTrue = callback(str, obj); // do some process and returns true/false.
         return isTrue ;
    }

Otros parámetros Ejemplos: - http://usejsdoc.org/tags-param.html

Esperando que esto te ayude :)