Aprende C++: Comentarios

Un comentario es una línea (o múltiples líneas) de texto que son insertadas en el código fuente para explicar qué está haciendo el código. Ahora verás los tipos de comentarios que existen y la manera correcta de usarlos.

 Tipos de comentarios

En C++ existen dos tipos de comentarios:

El símbolo // comienza un comentario de una sola línea en C++, que le dice al compilador que ignore todo lo que haya hasta el final de la línea, por ejemplo:

cout << "Hola mundo" << endl; // Todo lo escrito desde aquí es ignorado.

Normalmente, el comentario de una línea se usa para hacer un comentario rápido sobre esa línea de código.

cout << "Hola mundo" << endl; // cout y endl viven en la biblioteca iostream.

cout << "Encantado de conocerte" << endl; //estos comentarios lo
// hacen difícil de leer.

cout << "Si" << endl; // especialmente cuando las líneas son diferentes.

Teniendo comentarios a la derecha de una línea hace que tanto el código como el comentario sean difíciles de leer, particularmente si la línea es muy larga. Consecuentemente, el comentario // se suele colocar encima de la línea que se comenta.

// cout y endl viven en la biblioteca iostream.

cout << "Hola mundo" << endl;

// estos comentarios no lo hacen difícil de leer.

cout << "Encantado de conocerte" << endl;

// son más cómodos para la vista.  

cout << "Si" << endl;

El par de símbolos /* y */ denota un comentario de múltiples líneas, al estilo de C. Todo lo que haya entre esos símbolos es ignorado.

/* Este es un comentario de múltiples líneas.

Esta línea también será ignorada.

También lo será esta. */

Ya que todas las líneas serán ignoradas, verás que algunos programadores embellecerán todas esas líneas.

/* Este es un comentario de múltiples líneas.

 * Esta línea también será ignorada.

 * También lo será esta.

 */

 Los comentarios múltiples no se acumulan, así que lo siguiente podría traer resultados inesperados:

/* Esto es un comentario de múltiples líneas /* comentario */ Esto no está dentro del comentario */

Regla: nunca coloques comentarios dentro de otros comentarios.

Uso apropiado de los comentarios

Normalmente, los comentarios deberían ser usados para tres cosas. Primero, en la biblioteca, programa o función, los comentarios deberían ser usados para describir qué hace la biblioteca, función o programa. Por ejemplo:

//Este programa calcula las notas de los alumnos basado en su examen y tareas.

//Esta función usa el método de Newton para aproximarse al resultado
//de la raíz de una ecuación dada.

//Estas líneas generan un objeto aleatorio basado en su rareza y nivel.

Todos estos comentarios le dan al lector una idea de qué el programa está intentando hacer sin tener que mirar todo el código. El usuario (posiblemente otra persona, o tú si estás intentando reusar el código que ya has escrito) puede decir con una ojeada si el código es relevante para lo que está intentando conseguir. Esto es importante cuando trabajas en un equipo, ya que no todo el mundo estará familiarizado con todo el código.

Segundo, dentro de una biblioteca, programa o función descrita arriba, los comentarios deberían usarse para describir cómo el código va a lograr su cometido.

*/ Para generar un objeto aleatorio, haremos lo siguiente:
 * 1) Colocar todos los objetos de la rareza deseada en una lista.
 * 2) Calcular la probabilidad para cada objeto basándonos en su nivel.
 * 3) Elegir un número aleatorio.
 * 4) ...
 ...
*/

Estos comentarios le da al usuario una idea de cómo va a funcionar el código sin ir en mucho detalle.

A nivel de declaración, los comentarios deberían usarse para describir por qué el código está haciendo algo. Un mal comentario para las declaraciones explicaría qué está haciendo. Si alguna vez escribes un código tan complejo que requiera comentar qué está haciendo cada declaración, posiblemente necesites reescribirlo todo, no comentarlo.

Aquí van algunos ejemplos:

Mal comentario

// Determina el rango de visión a 0.
vision = 0;

 Se puede ver claramente en la declaración que la visión es 0.

Buen comentario

// El jugador acaba de tomarse una poción de ceguera.
vision =  0;

Ahora sabemos por qué la visión es 0.

Mal comentario

// Calcula el precio de los objetos.
precio = objetos / 2 * precioTienda;

Sí, podemos ver que se está calculando el coste, pero ¿por qué se divide entre 2?

Buen comentario

// Se divide los objetos entre 2 porque se compran en pares.
precio = objetos / 2 * precioTienda;

¡Ahora lo sabemos!

A veces los programadores tienen que tomar una dura decisión entre resolver un problema de una manera u otra. Los comentarios son una buena forma de recordarte (o decirle a otras personas) por qué tomaste una decisión.

// Hemos decidido usar una lista en vez de un array porque
// los arrays son muy lentos a la hora de ... 

Para finalizar, los comentarios deberían ser escritos de una manera en la que alguien que no tenga ni idea de qué hace el código, lo entienda. En el caso de que algún día digas "Es obvio que el código hace esto, es imposible que me olvide" y resulte que no es tan obvio, te darás cuenta de lo rápido que lo puedes olvidar. Te agradecerás (o te lo agradecerá otra persona) por escribir qué, cómo y por qué del código en lenguaje humano. Leer líneas individualmente es fácil, entender qué hacen en conjunto no tanto.

En resumen

• En una biblioteca, programa o función, describe qué.
• Dentro de una biblioteca, programa o función, describe cómo.
• En una declaración describe por qué.

Los comentarios también son útiles cuando estás tratando de encontrar algún error o alguna línea da problemas en el compilador, ya que puedes comentar esa línea de código y ejecutar el programa para comprobar cómo se comporta.

Aprende lo que son las variables y cin