Comentario (informática)

«//» redirige aquí. Para otras acepciones, véase // (desambiguación).

En la programación de computadoras, un comentario es una construcción del lenguaje de programación^[1]​ destinada a incrustar anotaciones legibles al programador en el código fuente de un Programa informático.^[2]​ Estas anotaciones son potencialmente significativas para los programadores, pero usualmente ignorados por los compiladores e intérpretes.^[3]​^[4]​ 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.

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.

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").^[5]​

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).^[6]​^[7]​^[8]​

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.^[8]​

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 --.^[8]​

Usos

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

Planeació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."^[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") 

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.^[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); 

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.^[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]​

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

Artículo principal: Generador de documentación

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.

Ddoc para el [[lenguaje de programacinet 

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]​

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

En archivo.js pueden darse las siguientes formas:

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

Referencias

1. Para los propósitos de este artículo, los comentarios de un lenguaje de programación son tratados indistintamente de comentarios que aparecen en lenguajes de marcas, archivos de configuración u otros contextos similares. Más aún, los lenguajes de marcas con frecuencia se relacionan de manera cercana con código de lenguajes de programación, especialmente en el contexto de generación de código. Ver por ejemplo Ganguli, Madhushree (2002). Making Use of Jsp (en inglés). Nueva York: Wiley. ISBN 0471219746. , Hewitt, Eben (2003). Java for Coldfusion Developers (en inglés). Upper Saddle River: Pearson Education. ISBN 0130461806. 
2. Source code can be divided into program code (which consists of machine-translatable instructions); and comments (which include human-readable notes and other kinds of annotations in support of the program code).Penny Grubb, Armstrong Takang (2003). Software Maintenance: Concepts and Practice (en inglés). World Scientific. pp. 7, 120–121. ISBN 981238426X. 
3. Algunos entornos de programación incluyen los comentarios como uno de los elementos de la sintaxis del lenguaje que son retenidos para procesamiento posterior, en lugar de ser descartados una vez han sido reconocidos por el procesador de lenguaje.
4. Los comentarios deben ser indicados de tal manera que sea posible para el procesador de código fuente reconocerlos como tal. Esto es usualmente simplificado al decir que los comentarios son "ignorados" (luego de ser reconocidos y desechados) por el procesador.
5. Dixit, J.B. (2003). Computer Fundamentals and Programming in C (en inglés). Laxmi Publications. ISBN 8170088828. 
6. Desmond, Higham (2005). MATLAB Guide (en inglés). SIAM. ISBN 0898715784. 
7. Vermeulen, Al (2000). The Elements of Java Style (en inglés). Cambridge University Press. ISBN 0521777682. 
8. «Using the right comment in Java» (en inglés). Consultado el 24 de julio de 2007. 
9. W. R., Dietrich (2003). Applied Pattern Recognition: Algorithms and Implementation in C++ (en inglés). Springer. p. 66. ISBN 3528355581.  ofrece puntos de vista sobre el uso adecuado de comentarios en el código fuente
10. Keyes, Jessica (2003). Software Engineering Handbook (en inglés). CRC Press. p. 256. ISBN 0849314798.  discute los comentarios y la ciencia de la documentación
11. The Elements of Programming Style, Kernighan & Plauger
12. Code Complete, McConnell
13. Spinellis, Diomidis (2003). Code reading: The Open Source Perspective (en inglés). Addison-Wesley. ISBN 0201799405. 
14. . Archivado desde el original el 14 de julio de 2007. Consultado el 24 de julio de 2007. 
15. Niederst, Jennifer (2006). Web Design in a Nutshell: A Desktop Quick Reference (en inglés). O'Reilly. ISBN 0596009879. En ocasiones la diferencia entre un "comentario" y otros elementos de la sintaxis de un lenguaje de programación o de marcas implica matices sutiles. Niederst indica una situación tal al decir: "Unfortunately, XML software thinks of comments as unimportant information and may simply remove the comments from a document before processing it. To avoid this problem, use an XML CDATA section instead."
16. Véase e.g., Wynne-Powell, Rod (2008). Mac Os X for Photographers: Optimized Image Workflow for the Mac User (en inglés). Oxford: Focal Press. p. 243. ISBN 0240520270. 
17. Lamb, Linda (1998). Learning the VI Editor (en inglés). Sebastopol: O'Reilly & Associates. ISBN 1565924266.  describe el uso de sintaxis modeline en los archivos de configuración de Vim
18. Ver e.g., Berlin, Daniel (2006). Practical Subversion, Second Edition (en inglés). Berkeley: APress. p. 168. ISBN 1590597532. 
19. Ambler, Scott (2004). The Object Primer: Agile Model-Driven Development with UML 2.0 (en inglés). Cambridge University Press. ISBN 1397805218. 
20. Murach. C# 2005. p. 56. 

Enlaces externos

• (en inglés)

•   Datos: Q1141067