Comentario (informática)

Este artículo o sección necesita referencias que aparezcan en una publicación acreditada, como revistas especializadas, monografías, prensa diaria o páginas de Internet fidedignas. Puedes añadirlas así o avisar al autor principal del artículo en su página de discusión pegando: {{subst:Aviso referencias|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 integrar información adicional en el código fuente de un programa. En la mayoría de los casos, cuando el código fuente es procesado por un compilador o intérprete, los comentarios no se toman en cuenta.

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 recomiendan adoptar "filosofías" o metodologías para la correcta utilización de los comentarios.

Información general

El código fuente se puede dividir conceptualmente en código fuente (consistente en instrucciones inteligibles por la computadora) y comentarios (que consisten en notas inteligibles por el ser humano, además de ciertas anotaciones para dar soporte al código fuente). Las reglas y sintaxis de ambos están descritas en la especificación del lenguaje de programación.

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

Un comentario de bloque delimita una zona del código fuente compuesta por 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 unos dentro de otros (e.g., MATLAB), pero otros lenguajes (e.g., Java) no lo admiten.

Un comentario 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 algunos lenguajes, el comentario de línea siempre comienza en una cierta columna 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 línea. Por ejemplo, el lenguaje C++ usa los delimitadores /* y */ para los comentarios de bloque mientras que los comentarios de línea utilizan el delimitador //. Otros lenguajes solamente admiten un tipo de comentario. Por ejemplo, ADA solamente dispone de comentarios de línea mediante el delimitador --.

Usos

La manera de dar uso a los comentarios es objeto de controversia con posiciones a menudo enfrentadas.

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, la necesidad de volver a explicar el código puede ser un signo de que es demasiado complejo y debe ser reescrito.

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 es especialmente relacionado con ciertos proyectos de escaso tiempo de desarrollo, o en la corrección de errores.

Descripción algorítmica

A veces, el código fuente contiene una solución a un problema digno de mención específica. 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 en la tarea de mantener la base del código se puede encontrar esta explicación fundamental.

Por ejemplo, un programador puede agregar un comentario para explicar por qué un tipo de inserción fue elegido en lugar de una ordenación rápida, pues la primera es, en teoría, más lento que el segundo sin embargo puede que en el ejemplo no se está buscando rendimiento sino estabilidad.

Inclusión de recursos

Diagramas y otros tipos de herramientas de ayuda gráfica pueden ser insertadas en el código fuente en forma de comentario. Además, los avisos de derechos de autor, fecha de creación, versión del producto, contacto con el propietario y/o creador, etc. puede ser embebido en código fuente como comentarios.

Debugging

Una práctica común es comentar un fragmento de código, de modo que no se ejecutará en el programa final, pero si da una idea de que se podría o se quiso haber hecho en el programa, aveces también es usado para dejar las bases de una nueva versión del software.

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

El código de arriba sugiere que el programador prefirió desactivar la opción de debugging por alguna razón. Este estilo de comentario es más adecuado para el debugging. Un carácter de barra simple delante del delimitador de apertura es el que permite habilitar o deshabilitar los comentarios en bloque.

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 cabecera del archivo, los comandos para configurar el modo de resaltar el archivo de sintaxis o el número de revisión del archivo. Estos comentarios son el control funcional también conocido comúnmente como anotaciones. Mantener la documentación de comentarios del código fuente se considera como una forma de simplificar el proceso de documentación, así como aumentar las posibilidades de que la documentación se mantendrá al día con los cambios en el código. Normalmente este tipos de comentarios conlleva a 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# y Visual Basic implementan una característica similar llamada comentarios XML, que son leídos por IntelliSense desde el compilado .NET.^[1]

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

/*comentario 
de bloque*/

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

C/C++

//comentario en línea

/* comentario 
en bloque*/

#if 0
Comentario de bloque
aunque el bloque contenga
/* este tipo de comentarios */
#endif

Lua

-- Un comentario de línea

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

Ruby

#comentario

=begin
comentario de bloque
=end

Python

#comentario

Perl

#comentario

Javascript

En archivo .js pueden darse las siguientes formas:

//comentario en línea

/* comentario
en bloque */

En las páginas webs , aparte de las anteriores formas también está el comentario HTML:

<!--
  sentencias javascript no obviadas
 // -->

SQL

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

/* y este
en bloque */

Visual Basic

'comentario

'''comentario XML

PHP

//comentario en línea

#este también

/* comentario
en bloque */

Cobol

* Comentario

Referencias

Enlaces externos

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