Comentario (informática)

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.

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."[11]

"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"[12]

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")

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.[13]

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);

Logotipos, diagramas y diagramas de flujo consistentes en construcciones de arte ASCII pueden ser insertados en el código fuente en forma de comentario.[14] 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.[15]

<!-- 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.[15]

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.

Las herramientas de programación en ocasiones incorporan documentación y metadatos en los comentarios.[16] 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[17] o el número de revisión del archivo.[18] 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.[19] 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.[20]

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.

 //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
 */

  //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
  *)

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

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