Comentarios : explicaciones del código fuente del programa , ubicado directamente dentro del código comentado. La sintaxis de los comentarios está definida por el lenguaje de programación . Desde el punto de vista del compilador o intérprete , los comentarios son parte del texto del programa que no afecta su semántica. Los comentarios no tienen efecto sobre el resultado de la compilación del programa o su interpretación. Además del código fuente del programa, los comentarios también se utilizan en lenguajes de marcas y lenguajes de descripción .
La mayoría de los expertos están de acuerdo en que los comentarios deben explicar la intención del programador , no el código; lo que se puede expresar en un lenguaje de programación no se debe comentar; en particular, se deben usar nombres significativos para las variables, funciones, clases, métodos y otras entidades (ver Convenciones de nomenclatura ), dividir el programa en partes fáciles de entender, esforzarse por hacer que la estructura de clases y la estructura de la base de datos sean lo más comprensibles y transparentes posible, etc. Incluso existe la opinión (se sigue en programación extrema y algunas otras metodologías de programación flexible ) de que si se requieren comentarios para comprender el programa, significa que está mal escrito.
El concepto de programación alfabetizada insiste en la inclusión de comentarios tan detallados y reflexivos en el texto del programa que se convierte en el texto fuente no solo para el código ejecutable, sino también para la documentación que lo acompaña .
Los comentarios se utilizan a menudo para deshabilitar temporalmente un fragmento de código. En C y C++ , algunos[ quien? ] recomienda usar directivas de preprocesador ( #if 0... #endif) para el mismo propósito.
En cuanto a la sintaxis, hay dos tipos de comentarios. Un comentario de varias líneas puede tener cualquier longitud y está marcado con caracteres especiales al principio y al final (por ejemplo, /* */). Algunos idiomas permiten anidar comentarios de varias líneas, otros no.
Un comentario de una sola línea se marca con un carácter especial al principio (por ejemplo, //) y continúa hasta el final de la línea. Normalmente, los comentarios de una línea se pueden anidar dentro de otros comentarios de una o varias líneas. Los métodos de grabación se pueden intercalar, desde el punto de vista de la semántica, son los mismos.
Otro tipo de comentarios, las anotaciones , se utilizan en bocetos de pruebas de la corrección de los programas. Dichos comentarios describen el estado de la computadora cuando el programa, durante la ejecución, alcanza el punto donde se encuentra el comentario. Un programa anotado se llama programa anotado .
Los comentarios con formato especial (los llamados comentarios de documentación ) se utilizan para crear documentación automáticamente , principalmente para bibliotecas de funciones o clases . Para ello se utilizan generadores de documentación , por ejemplo, como javadoc [1] para el lenguaje Java , phpDocumentor para PHP [2] , doxygen [3] para C y C++ , etc.
Los comentarios de la documentación suelen tener el formato de comentarios de estilo C de varias líneas . En cada caso, el comentario debe ir antes del elemento documentado. El primer carácter de un comentario (y al comienzo de las líneas de comentario) debe ser *. Los bloques están separados por líneas en blanco.
Ejemplo de comentario de documentación
/** * Nombre del objeto o descripción breve * * Descripción ampliada * * @descriptor_name value * @return data_type */En algunos entornos de programación (por ejemplo , Eclipse , NetBeans , Python , Visual Studio ), los comentarios de documentos se utilizan como una sugerencia interactiva en la interfaz de clases y funciones.
Durante la traducción, los comentarios se reconocen en la etapa de análisis léxico (y, por lo tanto, se consideran tokens ). El reconocimiento en la etapa de preprocesamiento es costoso e incluso está plagado de errores; incluir comentarios en los diagramas de sintaxis es casi imposible.
El compilador debe ignorar los comentarios, pero en la práctica no siempre es así. Algunos comandos especiales para el traductor, que dependen en gran medida de la implementación del lenguaje de programación, suelen formatearse como comentarios.
Por ejemplo, en el dialecto de Turbo Pascal , pragmas {$I-}y {$I+}se usan para deshabilitar y habilitar la verificación de errores de E/S estándar. Se utilizan comentarios especiales similares en el lenguaje de marcado HTML para indicar el tipo de un documento SGML , hojas de estilo "de escape" y secuencias de comandos en JavaScript y VBScript :
<!DOCTYPE HTML PÚBLICO "-//W3C//DTD HTML 4.0//EN" "http://www.w3.org/TR/REC-html40/strict.dtd"> … < TIPO DE ESTILO = "texto/css" > <! -- … descripción de estilos -- > </ STYLE > … < SCRIPT TYPE = "text/javascript" > <!-- ocultar el contenido del script de los navegadores más antiguos ... código de script JavaScript // fin del contenido oculto --> < / SCRIPT >Algunos programadores utilizan comentarios en el curso de su trabajo. Comentarios como este son especialmente útiles cuando varios desarrolladores están trabajando en el mismo código. Por ejemplo, un comentario TODO se suele utilizar para marcar una sección de código que el programador deja sin terminar para volver a ella más tarde. Un comentario de FIXME señala un error que se ha encontrado y se decide corregir más tarde. El comentario XXX indica que se encontró un error crítico, sin corregir qué trabajo adicional no se puede continuar.