Guía de estilo JavaScript: comentarios proyectos. JSDoc. @param, @return, @extends. Ejemplos (CU01192E)

Codificación aprenderaprogramar.com: CU01192E

GUÍA DE ESTILO PARA COMENTARIOS

Los programadores JavaScript suelen atenerse a unas reglas de estilo a la hora de escribir código. Esto no sólo es válido para el código en sí, sino también para los comentarios. En proyectos de gran extensión pueden existir miles de líneas de código JavaScript. Este código debe estar bien comentado para facilitar su comprensión y mantenimiento.

MANUALES DE ESTILO

En una empresa en la que trabajan 100 ó 1000 programadores cada programador no puede “hacer las cosas a su manera”. En estas empresas es frecuente que cada programador desarrolle un fragmento de una aplicación y luego esos fragmentos hay que unirlos. Para que esa unión sea sólida y no haya problemas de integración y mantenimiento posterior, todos los programadores deben atenerse a unas mismas normas.

Lo ideal sería que en una aplicación donde han trabajado 20 programadores, un supervisor no fuera capaz de detectar qué parte del código ha hecho cada programador. Esto es difícil, porque cada programador deja su impronta, pero siguiendo unas reglas predefinidas se puede conseguir como resultado un código bien estructurado y bastante homogéneo.

Ya hemos hablado de reglas de estilo a la hora de crear código en relación formas de uso preferentes del lenguaje y en relación  a cuestiones organizativas relacionadas con el código.

Vamos a centarnos ahora en los comentarios dentro del código JavaScript. No hay unas reglas obligatorias que cumplir en relación a los comentarios. Cada empresa puede usar diferentes estilos a la hora de comentar el código, si bien es cierto que suele hacerse de forma similar cuando hablamos de programación profesional.

Nosotros vamos a presentar aquí unas reglas de estilo para comentarios que se corresponden con las que utilizan grandes empresas, pero ten en cuenta que ni son obligatorias ni todas las empresas siguen los mismos criterios.

REGLAS DE ESTILO PARA COMENTARIOS

A continuación presentamos una lista de reglas de estilo que suelen recomendarse para la programación JavaScript. Como hemos indicado, son opcionales, pero un programador que no sigue unas reglas de estilo no suele considerarse un buen programador. Más que seguir estrictamente estas reglas que presentamos a continuación, lo importante es que cuando crees código sigas unas reglas de estilo (que pueden ser estas o similares a estas) y que no las modifiques. De esa manera crearás código homogéneo.

También ten en cuenta que las reglas aquí presentadas son una forma resumida de reglas respecto a lo que sería un manual de estilo propio de una empresa, que sería mucho más extenso. El objetivo de presentar aquí estas reglas es didáctico y para familiarizarnos con ellas, no consideres que son obligatorias ni que aquí tienes todas las reglas necesarias.

Las reglas aquí presentadas siguen el estándar JSDoc. Seguir un estándar tiene ventajas como poder generar de forma automática documentación de proyectos usando el software adecuado.

Regla 1. El mejor comentario es el implícito o auto-documentador

Considera que estás revisando un código y que en una función encuentras esto:

function f33 (a, b) { … }

¿Te haces una idea de lo que hace esta función? ¿Te haces una idea de qué tipo de parámetros recibe la función? Difícilmente nos podremos hacer una idea si los nombres de variables, funciones, parámetros, etc. son cortos y no descriptivos.

Sería mucho mejor esto:

function getFullName (name, surname) { … }

Fíjate que estamos usando nombres descriptivos. En este caso hemos usado el inglés para que tengas en cuenta que el inglés es el lenguaje más universalmente utilizado en programación. No solo lo utilizan quienes hablan inglés, sino que lo utilizan muchas empresas aunque sean de habla hispana. Si prefieres utilizar el español puedes escribirlo así:

function obtenerNombreCompleto (nombre, apellidos) { … }

Este código, aunque no hemos comentado nada, podemos decir que está autodocumentado, porque se entiende (aproximadamente) lo que hace simplemente leyéndolo. Esto es un buen estilo de programación.

Regla 2. Usa un estilo de comentarios y no lo cambies, pero respeta el existente

Si estamos trabajando en un nuevo proyecto usaremos un estilo para comentarios que debemos mantener en todo el proyecto. Sin embargo, si estamos revisando el código desarrollado por otras personas y observamos que siguen un estilo de comentarios diferente al que nosotros estemos habituados a usar, deberemos respetarlo (para no afectar a la homogeneidad del código).

El estilo de comentarios que vamos a proponer aquí es un estilo similar al que se usa en otros lenguajes de programación como C++ y Java.

Regla 3. Usa comentarios multilínea en cabeceras de funciones y en línea en otros casos

Para comentar lo que hace una función usaremos comentarios de este tipo:

Si una línea es demasiado larga la dividimos en varias líneas. La primera estará sin indentar y el resto indentada (desplazada hacia dentro) respecto de la primera.

Los comentarios puntuales en línea se harán con //. Por ejemplo:

var tmpPers; //Variable temporal que almacenará un objeto Persona

Regla 4. Usa un comentario al principio de un archivo js para describir su contenido

En un proyecto podemos tener decenas de archivos js correspondientes a código JavaScript. Al principio de cada archivo deberíamos incluir un comentario descriptivo de qué contiene dicho archivo que comenzará con la etiqueta @fileoverview. Por ejemplo:

Regla 5. Documenta las funciones incluyendo los parámetros que usa y lo que devuelve

Un comentario típico para describir una función incluirá una descripción de lo que hace la función, la descripción de sus parámetros, y la descripción de lo que devuelve la función.

La descripción de un parámetro se hace comenzando con @param

La descripción de lo que devuelve la función se hace comenzando con @return. Si la función no devuelve nada se omitirá esta etiqueta.

Ejemplo:

Regla 6. Usa comentarios para constructores y para documentar las propiedades

Si estamos definiendo un tipo de objeto usaremos una declaración @constructor para indicar que estamos definiendo el constructor para un tipo de objeto. Además, las propiedades serán comentadas para reflejar su significado. La etiqueta @type se usará para describir qué tipo de dato corresponde a la propiedad.

Ejemplo:

Regla 7. Usa etiquetas normalizadas

Cuando queramos incluir una descripción de un elemento usaremos etiquetas normalizadas. Por ejemplo una etiqueta normalizada para describir al autor de un código es @author. En cambio no es normalizada <<@autor>> ni <<@Author>> ni <<@authors>>.

A continuación indicamos la lista de etiquetas normalizadas recomendadas: