Comentarios y Documentación

Comentarios

Los comentarios son muy útiles para introducir aclaraciones en el código y así mejorar su legibilidad. Los comentarios son ignorados por el compilador o intérprete.

En muchos lenguajes de programación se insiste en utilizar nombres de variables y métodos muy expresivos, de forma que los comentarios sean prácticamente innecesarios.

// Comentario de una línea

int i = 0; // Comentarios para explicar la variable i

/* Comentario de
varias líneas */

En los lenguajes C, C++, Java, JavaScript, C# y Kotlin disponemos de dos tipos de comentarios. Usa // para comentar los caracters a la derecha. Usa /* y */ para comentar los caracteres entre ellos.

// Comentario de una línea

int i = 0; // Comentarios para explicar la variable i

/* Comentario de
varias líneas */

// Comentario de una línea

i = 0; // Comentarios para explicar la variable i

/* Comentario de
varias líneas */

# Comentario de una línea

i = 0 # Comentarios para explicar la variable i

""" Comentario de
    varias líneas """

''' Los strings también se pueden definir 
    usando comillas simples. Se utiliza la triple 
    comilla cuando queremos usar varias líneas '''

En Python usa el símbolo # para comentar los caracters a la derecha. También se puede introducir comentarios de varias líneas definiendo un string sin asignar por medio de triple comillas """ o '''.

// Comentario de una línea

i = 0; // Comentarios para explicar la variable i

/* Comentario de
varias líneas */

% Comentario de una línea

i = 0 % Comentarios para explicar la variable i

%% Divisor de sección

En MATLAB usa el símbolo % para comentar los caracters a la derecha. También se puede introducir un divisor de sección con % más un espacio.

// Comentario de una línea

var i: Int // Comentarios para explicar la variable i

/* Comentario de
varias líneas */

# Comentario de una línea

i = 0 # Comentarios para explicar la variable i

=begin 
aquí comienza un comentario 
de varias líneas
=end i = i + 1 #Esto ya no es un comentario

En Ruby y Perl usa el símbolo # para comentar los caracters a la derecha. Puedes insertar comentarios de varias líneas usando la notación POD

Documentación

Muchos lenguajes de programación incorporan sistemas que nos permiten documentar las clase, funciones o variables en el mismo fichero donde escribimos el código. Es similar a los comentarios, pero con la ventaja que la documentación es reconocida por el sistema. Gracias a esto podremos generar la documentación de nuestro código de forma automática, o que nuestras clases o funciones se incorporen automáticamente al sistema de ayuda del entorno de desarrollo.

Veamos un ejemplo. Muchos entornos de desarrollo muestran información sobre una función cuando situamos el ratón sobre ella. Si has escrito documentación para una función escrita por ti, cuando sitúes el ratón sobre tu función, también mostrará la ayuda:

/**
 * Aquí comienza la documentación de la clase.
 * Explicamos su uso.
 * @author Nombre del autor
 */
public class Clase {
   /**
    * Documentación de la variable
    */
   private int variable;
 
   /**
    * Documentación de un método. 
    * Calcula una potencia
    *
    * @param base La base de la potencia
    * @param exponete El exponente de la potencia
    * @return Devuelve la base elevada al exponente
    * @throws UndefinedException si ambos parámetros son 0
    */
   public double potencia(double base, double exponente) throws UndefinedException{
      //...código
   }
}

Java utiliza un sistema de comentarios para documentar el código conocido como javadoc. Todo comentario que introduzcamos de la forma /** … */ será utilizado por Java para documentar el elemento que es definido a continuación. Este elemento puede ser una clase, una variable o un método. Podemos usar etiquetas usando el carácter @.

class Clase(object):
   """
   Este es el docstring que permite documentar esta clase.
   Tradicionalmente se utiliza triple comilla, para poder usar varias líneas.
   Pero no es obligatorio.
   """
   def potencia(base, exponente):
      """Este es el docstring del método."""
      pass

En Python utiliza un String literal en la primera expresión tras una clase, módulo o función para documentarlos. Este String se conoce como docstring y puedes consultarlo en tiempo de ejecución usando el atributo .__doc__.

El módulo pydoc genera automáticamente documentación a partir de módulos Python. La documentación puede presentarse como páginas de texto en la consola, servirse en un navegador web o guardarse en archivos HTML. La información mostrada se obtiene del atributo .__doc__ Desde el interprete usa el comando help(Clase) para que pydoc nos muestre información sobre la clase.

/**
 * Aquí comienza la documentación de la clase.
 * Explicamos su uso.
 * @author Nombre del autor
 * @since version 1.1.51.
 * @param T Explicación del usu del tipo T.
 * @property propiedad Explicación de esta propiedad.
 * @constructor Explicación del constructor.
 */
public class Clase<T>(val propiedad:String) {
   /**
    * Documentación de un método. 
    * Calcula una potencia
    *
    * @param base La base de la potencia
    * @param exponete El exponente de la potencia
    * @return Devuelve la base elevada al exponente
    * @throws UndefinedException si ambos parámetros son 0
    */
   fun potencia(base: Double, exponente: Double): Double {
      //...código
   }
}

Kotlin utiliza un sistema de comentarios para documentar el código conocido como KDoc. ES muy similar a Javadoc. Todo comentario que introduzcamos de la forma /** … */ será utilizado para documentar el elemento que es definido a continuación. Este elemento puede ser una clase o un método. Podemos usar etiquetas usando el carácter @.