Comentario (informática)

Un ejemplo de código fuente de Java, con comentarios de prólogo en rojo, comentarios entre líneas en verde. Código del programa en azul.

En la programación de computadoras, un comentario es una construcción del lenguaje de programación​ destinada a incrustar anotaciones legibles al programador en el código fuente de un Programa informático.​ Estas anotaciones son potencialmente significativas para los programadores, pero usualmente ignorados por los compiladores e intérpretes.​​ Los comentarios son añadidos usualmente con el propósito de hacer el código fuente más fácil de entender con vistas a su mantenimiento o reutilización. La sintaxis y reglas para los comentarios varían y usualmente son definidas en la especificación del lenguaje de programación.

Se ha de tener en cuenta que los comentarios necesitan mantenimiento igual que el código y, por tanto, que un comentario preciso y conciso es más fácil de mantener que uno largo, repetitivo y complicado.

Los comentarios tienen una amplia gama de posibles usos: desde la mejora del código fuente con descripciones básicas hasta la generación de documentación externa. También se utilizan para la integración con sistemas de control de versiones y otros tipos de herramientas de programación externas.

La flexibilidad proporcionada por los comentarios da pie a un amplio abanico de formas de uso distintas y a la inclusión de información inútil dentro del código fuente. Para evitar este inconveniente, muchos programadores y analistas de software adoptan alguna de las "filosofías" o metodologías para la correcta utilización de los comentarios.

Información general

Los comentarios adoptan por norma general un formato o bien de "bloque" (también denominado de "prólogo") o bien de "fin de línea" (también denominado "inline").​

Un comentario de bloque delimita una zona del código fuente en la cual es permitido expandirse a varias líneas de texto. Esta región se reconoce por un delimitador de inicio y un delimitador de final del comentario. Algunos lenguajes de programación admiten que los comentarios se aniden recursivamente (e.g., MATLAB), pero otros lenguajes no lo admiten (e.g., Java).​​​

Un comentario de fin de línea comienza con un delimitador y continúa hasta el final de la línea de texto (es decir, no es necesario un segundo delimitador). En otros casos, el comentario de fin de línea comienza en una cierta columna dentro del código fuente no siendo necesario un delimitador.​

Los delimitadores son una secuencia conocida de caracteres y suelen ser distintos para los comentarios de bloque que para los de fin de línea. Por ejemplo, el lenguaje C++ usa, para los comentarios de bloque, los delimitadores /* y */ mientras que los comentarios de fin de línea utiliza el delimitador //. Otros lenguajes solamente admiten un tipo de comentario. Por ejemplo, ADA solamente dispone de comentarios de fin de línea mediante el delimitador --.​

Usos

La mejor manera de dar uso a los comentarios es objeto de controversia con posiciones a menudo enfrentadas.​​ Hay una gran variedad de formas de escribir comentarios y muchos comentaristas que ofrecen, en ocasiones, consejos contradictorios.​

Planificación / Revisión

Los comentarios se pueden utilizar como una forma de pseudocódigo para describir la intención antes de escribir el código real. En este caso se debe explicar la lógica detrás del código en lugar del código en sí mismo.

/* itera hacia atrás por todos los elementos retornados por el servidor (estos deben ser procesados cronológicamente)*/
for (i = (numElementsReturned - 1); i >= 0; i--){
    /* procesa los datos de cada elemento */
    updatePattern(i, returnedElements[i]);
}

Si se deja este tipo de comentario luego de escribir el código, se simplifica el proceso de revisión al permitir la comparación directa del código con los resultados previstos. Una falacia lógica común es que el código fácil de entender hace lo que tiene que hacer.

Descripción de código

Los comentarios pueden ser utilizados para resumir el código o para explicar la intención del programador. Según esta escuela de pensamiento, re-explicar el código en lenguaje natural se considera superfluo y la necesidad de volver a explicar el código puede ser un signo de que es demasiado complejo y debe ser reescrito.

"No documentes mal código – re-escríbelo."​

"Los buenos comentarios no repiten el código, ni lo explican. Estos aclaran su intención. Los comentarios deben explicar, a un nivel de abstracción más alto que el propio código, lo que se intenta conseguir"​

Los comentarios también pueden ser utilizados para explicar por qué un bloque de código no se ajusta a las convenciones o las buenas prácticas. Esto está especialmente relacionado con proyectos de escaso tiempo de desarrollo, o en la corrección de errores. Por ejemplo:

' Se asigna una segunda variable debido a que se producen errores 
' en el servidor cuando se reutilizan los datos del formulario. No se encontró documentación
' sobre el comportamiento extraño del servidor, así que simplemente se codificó para resolverlo.
vtx = server.mappath("local settings")

Descripción algorítmica

A veces, el código fuente contiene una solución nueva o digna de mencionarse a un problema específico. En tales casos, los comentarios pueden contener una explicación de la metodología. Estas explicaciones pueden incluir diagramas y pruebas matemáticas formales. Esto puede ser la explicación del código, en lugar de una clarificación de sus intenciones, pero otros encargados del mantenimiento del código pueden encontrar como fundamental esta explicación. Esto puede ser especialmente cierto en el caso de problemas de dominios de alta especialización; así como en optimizaciones, construcciones o llamadas a funciones de uso no cotidiano.​

Por ejemplo, un programador puede agregar un comentario para explicar por qué se eligió un Ordenamiento por inserción en lugar de quicksort, pues el primero es, en teoría, más lento que el segundo. Esto podría escribirse de la siguiente manera:

 list = [f (b), f (b), f (c), f (d), f (a), ...];
 // Se requiere un ordenamiento estable, mientras el desempeño realmente no importa.
 insertion_sort (list);

Inclusión de recursos

Logotipos, diagramas y diagramas de flujo consistentes en construcciones de arte ASCII pueden ser insertados en el código fuente en forma de comentario.​ Además, puede incrustarse como comentarios avisos de derechos de autor, fecha de creación, versión del producto, contacto con el propietario y/o creador, etc..

El fragmento de código que sigue es un simple diagrama ASCII que representa el flujo de proceso para un script de administración de sistemas contenido en un Fichero Windows Script que se ejecuta en Windows Script Host A pesar de que la sección que marca el código aparece como un comentario, el diagrama de hecho aparece en una sección XML CDATA sección, que técnicamente se considera distinta de los comentarios, pero que puede servir para propósitos similares.​

<!-- begin: wsf_resource_nodes -->
<resource id="ProcessDiagram000">
<![CDATA[
 HostApp (Main_process)
    |
    V
script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
                |
                |
                V
         mru.ini (mru_history)   
]]>
</resource>

Aun cuando este diagrama fácilmente podría haber sido incluido como un comentario, el ejemplo ilustra un caso en que el programador puede optar por no utilizar los comentarios, como una forma de incluir recursos en el código fuente.​

Depuración

Una práctica común entre programadores es comentar un fragmento de código, es decir, agregar delimitadores de modo que un bloque de código se convierta en un comentario, y por tanto no se ejecutará en el programa final. Esto podría hacerse para excluir algunas piezas del código del programa o, de manera más común, para encontrar la causa de un error. Comentando sistemáticamente y ejecutando partes del programa, la causa del error puede ser determinada, permitiendo su corrección. A continuación un ejemplo de cómo comentar código con el propósito de excluirlo:

 if (opt.equals ("e"))
   opt_enabled = true;
 /*
  if (opt.equals ("d"))
   opt_debug = true;
 // */
 //*
 if (opt.equals ("v"))
    opt_verbose = true;
 // */

El fragmento de código de arriba sugiere que el programador optó por desactivar la opción de depuración por alguna razón. Este estilo específico de comentario es más adecuado para la depuración. Un carácter de barra simple delante del delimitador de apertura es el que permite habilitar o deshabilitar el comentarios de bloque completo.

Muchos EIDs permiten agregar o remover rápidamente este tipo de comentarios con opciones del menú singulares o atajos del teclado. El programador solamente debe marcar la parte de texto que desea comentar o descomentar y elegir la opción apropiada. Esto es particularmente útil con fragmentos grandes de código.

Generación de documentación

Las herramientas de programación en ocasiones incorporan documentación y metadatos en los comentarios.​ Estas pueden incluir las posiciones de inserción para la inclusión automática de archivos de cabecera, comandos para configurar el modo de resaltado de sintaxis​ o el número de revisión del archivo.​ Estos comentarios de control funcional son también conocidos comúnmente como anotaciones. Mantener la documentación dentro de comentarios en el código fuente es considerado como una forma de simplificar el proceso de documentación, así como un aumento en las posibilidades de que la documentación se mantendrá al día con los cambios en el código.​ Habitualmente este tipos de comentarios requiere utilizar una sintaxis básica para que puedan ser interpretados por el generador de documentación a diferencia de los comentarios anteriores donde no necesariamente se debe de utilizar una sintaxis predefinida.

Ejemplos de generadores de documentación son el programa javadoc, diseñado para ser utilizado con el lenguaje de programación Java, Ddoc para el lenguaje de programación D y doxygen, para ser usado con C/C++, Java IDL y PHPDoc para PHP.

C#, F# e implementan una característica similar llamada comentarios XML, que son leídos por IntelliSense para los ensamblados compilados del entorno.NET.​

Estilos

Hay muchas alternativas cuando se considera como los comentarios deben aparecer en el código fuente. Para grandes proyectos, los estilos de los comentarios se agregan apenas comienzan el proyecto. Normalmente los programadores prefieren estilos que son consistentes, no obstructivos, fáciles de modificar, y difíciles de romper.

Los siguientes fragmentos de código en C son solo un ejemplo de como los comentarios pueden variar de estilo, mientras todos contienen la misma información básica:

/* 
     Este es el cuerpo del comentario.
     Variante 1
*/

/***********************************\
* *
* Este es el cuerpo del comentario. *
* Variante 2. *
* *
\************************************/

Factores tales como la preferencia personal, la flexibilidad de las herramientas de programación, y otras consideraciones tienden a influir en las variantes de estilo utilizado en el código fuente.

Etiquetas

Algunas etiquetas se utilizan en los comentarios para ayudar en la indexación de los problemas comunes. Tales etiquetas son comúnmente resaltado de sintaxis y permite búsquedas con herramientas de programación común, como la utilidad grep de UNIX. Ejemplos de convenios etiqueta son:

• FIXME: para marcar código problemático potencial que requiere una atención especial y/o revisión.
• NOTE: peligros potenciales para documentar el funcionamiento interno del código y de indicar.
• TODO: para indicar las mejoras planificadas.
• XXX: para advertir a otros programadores de código problemático o equivoco.

Existe el riesgo de que las etiquetas se acumulan con el tiempo, es conveniente incluir la fecha y el propietario de etiqueta en el comentario de etiquetas para facilitar el seguimiento.

Curiosidades

Whitespace es un lenguaje de programación esotérico en el cual la sintaxis consiste únicamente en espacios en blanco, tabulador y líneas nuevas, cualquier otro carácter es ignorado, por lo que en este lenguaje cualquier escrito es un comentario.

Ejemplos

Ensamblador

 ;comentario

Java

 //comentario de línea

Que la línea son instrumentos que utilizamos en una variante de series

 /*comentario 
 de bloque*/

 /**
 comentario que será usado por javadoc
 */

Delphi

  //comentario en línea

  { comentario 
  en bloque }

  (* comentario 
  en bloque *)

En delphi se pueden anidar comentarios de bloque siempre que no usen el mismo delimitador, e.g.

  (* 
    comentario en bloque
    { 
      que contiene otros
      comentarios en bloque 
    }
    // o de fin de línea
    y que es perfectamente 
    válido
  *)

Lua

 -- Un comentario de línea

 --[[
     Un comentario de bloque
 ]]--

Ruby

 #comentario

 =begin
 comentario de bloque
 =end

Python

 #comentario

 """
 comentario
 en bloque
 """

Perl

 #comentario

Javascript

 //comentario en línea

 /* comentario
 en bloque */

código HTML

En las páginas webs .html se introduce el comentario entre <!-- --> .

 <!--
   esto es un comentario en código HTML 
  // -->

SQL

 //esto es un comentario
 --este también

 /* y este
 en bloque */

Visual Basic

 'comentario

 '''comentario XML

Pascal

  ' Comentario

PHP

 //comentario en línea

 #este también

 /* comentario
 en bloque */

Cobol

 * Comentario

Enlaces externos

• 13 consejos para comentar tu código
• Como escribir comentarios (en inglés)

• Datos: Q1141067