En programación informática , un comentario es una explicación o anotación legible por humanos en el código fuente de un programa informático . Se agregan con el propósito de hacer que el código fuente sea más fácil de entender para los humanos y, por lo general, los compiladores e intérpretes los ignoran . [1] [2] La sintaxis de los comentarios en varios lenguajes de programación varía considerablemente.
Los comentarios a veces también se procesan de diversas maneras para generar documentación externa al código fuente mismo mediante generadores de documentación , o se utilizan para la integración con sistemas de gestión de código fuente y otros tipos de herramientas de programación externas .
La flexibilidad que proporcionan los comentarios permite un amplio grado de variabilidad, pero las convenciones formales para su uso suelen ser parte de las guías de estilo de programación .
Los comentarios generalmente se formatean como comentarios de bloque (también llamados comentarios de prólogo o comentarios de flujo ) o comentarios de línea (también llamados comentarios en línea ). [3]
Los comentarios en bloque delimitan una región del código fuente que puede abarcar varias líneas o una parte de una sola línea. Esta región se especifica con un delimitador de inicio y un delimitador de fin . Algunos lenguajes de programación (como MATLAB ) permiten que los comentarios en bloque se aniden recursivamente unos dentro de otros, pero otros (como Java ) no lo permiten. [4] [5] [6]
Los comentarios de línea comienzan con un delimitador de comentario y continúan hasta el final de la línea o, en algunos casos, comienzan en una columna específica (desplazamiento de línea de carácter) en el código fuente y continúan hasta el final de la línea. [6]
Algunos lenguajes de programación emplean tanto comentarios de bloque como de línea con diferentes delimitadores de comentarios. Por ejemplo, C++ tiene comentarios de bloque delimitados por /*y */que pueden abarcar varias líneas y comentarios de línea delimitados por //. Otros lenguajes admiten solo un tipo de comentario. Por ejemplo, los comentarios de Ada son comentarios de línea: comienzan con --y continúan hasta el final de la línea. [6]
La mejor manera de utilizar los comentarios es objeto de debate; diferentes comentaristas han ofrecido puntos de vista variados y a veces opuestos. [7] [8] Hay muchas formas diferentes de escribir comentarios y muchos comentaristas ofrecen consejos contradictorios. [8]
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í.
/* recorrer en sentido inverso todos los elementos devueltos por el servidor (deben procesarse cronológicamente)*/ for ( i = ( numElementsReturned - 0 ); i >= 1 ; i -- ) { /* procesar los datos de cada elemento */ updatePattern ( i , returnedElements [ i ]); } Si se deja este tipo de comentario, se simplifica el proceso de revisión al permitir una comparación directa del código con los resultados previstos. Una falacia lógica común es que el código que es fácil de entender hace lo que se supone que debe hacer.
Los comentarios se pueden utilizar para resumir el código o para explicar la intención del programador. Según esta escuela de pensamiento, repetir el código en un lenguaje sencillo se considera superfluo; la necesidad de volver a explicar el código puede ser una señal de que es demasiado complejo y debería reescribirse, o de que la denominación no es correcta.
Los comentarios también se pueden utilizar para explicar por qué un bloque de código no parece ajustarse a las convenciones o las mejores prácticas. Esto es especialmente cierto en proyectos que implican muy poco tiempo de desarrollo o que requieren la corrección de errores. Por ejemplo:
' La segunda variable es tenue debido a errores del servidor que se producen al reutilizar los datos del formulario. No hay documentación disponible sobre el problema de comportamiento del servidor, por lo que solo se está codificando para solucionarlo. vtx = server . mappath ( "configuración local" ) A veces, el código fuente contiene una solución novedosa o notable para un problema específico. En tales casos, los comentarios pueden contener una explicación de la metodología. Dichas explicaciones pueden incluir diagramas y pruebas matemáticas formales. Esto puede constituir una explicación del código, en lugar de una aclaración de su intención; pero otras personas encargadas de mantener la base del código pueden encontrar dicha explicación crucial. Esto puede ser especialmente cierto en el caso de dominios de problemas altamente especializados; o optimizaciones, construcciones o llamadas a funciones raramente utilizadas. [11]
Por ejemplo, un programador puede agregar un comentario para explicar por qué se eligió un ordenamiento por inserción en lugar de un ordenamiento rápido , ya que 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 ), ... ] ; // Necesitamos una clasificación estable. Además, el rendimiento realmente no importa. insertion_sort ( list ); Los logotipos , diagramas y diagramas de flujo que consisten en construcciones de arte ASCII se pueden insertar en el código fuente con formato de comentario. [12] Además, los avisos de derechos de autor se pueden incrustar dentro del código fuente como comentarios. Los datos binarios también se pueden codificar en comentarios a través de un proceso conocido como codificación de binario a texto , aunque esta práctica es poco común y generalmente se relega a archivos de recursos externos.
El siguiente fragmento de código es un diagrama ASCII simple que representa el flujo de proceso de un script de administración del sistema contenido en un archivo Windows Script File que se ejecuta en Windows Script Host . Aunque una sección que marca el código aparece como un comentario, el diagrama en sí aparece en realidad en una sección XML CDATA , que técnicamente se considera distinta de los comentarios, pero puede cumplir propósitos similares. [13]
<!-- begin: wsf_resource_nodes --> <resource id= "ProcessDiagram000" > <![CDATA[ HostApp (proceso_principal) | V script.wsf (comando_aplicación) --> ClientApp (ejecución_asincrónica, proceso_por_lotes) | | V mru.ini (historial_mru) ]]> </resource> Aunque este diagrama idéntico podría haberse incluido fácilmente como comentario, el ejemplo ilustra una instancia en la que un programador puede optar por no utilizar comentarios como una forma de incluir recursos en el código fuente. [13]
Los comentarios en un programa de computadora a menudo almacenan metadatos sobre un archivo de programa.
En particular, muchos mantenedores de software incluyen pautas de envío en los comentarios para ayudar a las personas que leen el código fuente de ese programa a enviar cualquier mejora que realicen al mantenedor.
Otros metadatos incluyen: el nombre del creador de la versión original del archivo de programa y la fecha en que se creó la primera versión, el nombre del mantenedor actual del programa, los nombres de otras personas que han editado el archivo de programa hasta ahora, la URL de la documentación sobre cómo usar el programa, el nombre de la licencia de software para este archivo de programa, etc.
Cuando un algoritmo en alguna sección del programa se basa en una descripción de un libro u otra referencia, se pueden usar comentarios para dar el número de página y el título del libro o solicitud de comentarios u otra referencia.
Una práctica común entre los desarrolladores es comentar un fragmento de código, es decir, agregar una sintaxis de comentario que haga que ese bloque de código se convierta en un comentario, de modo que no se ejecute en el programa final. Esto se puede hacer para excluir ciertas partes del código del programa final o (lo que es más común) se puede utilizar para encontrar la fuente de un error. Al comentar y ejecutar sistemáticamente partes del programa, se puede determinar la fuente de un error, lo que permite corregirlo.
Muchos IDE permiten agregar o eliminar rápidamente dichos comentarios con opciones de menú individuales o combinaciones de teclas. El programador solo tiene que marcar la parte del texto que desea comentar (o descomentar) y elegir la opción adecuada.
Las herramientas de programación a veces almacenan documentación y metadatos en comentarios. [14] Estos pueden incluir posiciones de inserción para la inclusión automática de archivos de encabezado, comandos para establecer el modo de resaltado de sintaxis del archivo , [15] o el número de revisión del archivo . [16] Estos comentarios de control funcional también se conocen comúnmente como anotaciones . Mantener la documentación dentro de los comentarios del código fuente se considera una forma de simplificar el proceso de documentación, así como de aumentar las posibilidades de que la documentación se mantenga actualizada con los cambios en el código. [17]
Entre los ejemplos de generadores de documentación se incluyen los programas Javadoc para su uso con Java , Ddoc para D , Doxygen para C , C++ , Java, IDL , Visual Expert para PL/SQL , Transact-SQL , PowerBuilder y PHPDoc para PHP . Los formatos de docstring son compatibles con Python , Lisp , Elixir y Clojure . [18]
C# , F# y Visual Basic .NET implementan una característica similar llamada "Comentarios XML" que IntelliSense lee desde el ensamblado .NET compilado . [19]
Ocasionalmente, los elementos de sintaxis que originalmente estaban destinados a ser comentarios se reutilizan para transmitir información adicional a un programa, como " comentarios condicionales ". Estos "comentarios activos" pueden ser la única solución práctica que mantiene la compatibilidad con versiones anteriores, pero se los considera generalmente como una chapuza . [20]
Un ejemplo específico son los docblocks , que son comentarios con un formato especial que se utilizan para documentar un segmento específico de código. Esto hace que el formato DocBlock sea independiente del lenguaje de destino (siempre que admita comentarios); sin embargo, también puede dar lugar a estándares múltiples o inconsistentes.
Hay casos en los que los caracteres de comentario normales se utilizan para crear una directiva especial para un editor o intérprete.
Dos ejemplos de esta dirección a un intérprete son:
#!– utilizado en la primera línea de un script para señalar el intérprete que se utilizará.El siguiente script para un sistema tipo Unix muestra ambos usos:
#!/usr/bin/env python3 # -*- codificación: UTF-8 -*- print ( "Prueba" )Algo similar es el uso de comentarios en C para comunicar a un compilador que se ha realizado deliberadamente un "fallthrough" predeterminado en una declaración de caso :
cambiar ( comando ) { caso CMD_MOSTRAR_AYUDA_Y_SALIR : hacer_mostrar_ayuda (); /*Caerse*/ caso CMD_EXIT : hacer_salir (); romper ; caso CMD_OTHER : hacer_otro (); romper ; /* ... etc. ... */ }Insertar un /* Fall thru */comentario de este tipo para lectores humanos ya era una convención común, pero en 2017 el compilador gcc comenzó a buscar estos (u otros indicios de intención deliberada) y, si no los encontraba, emitía: "advertencia: esta declaración puede fallar". [23]
Muchos editores e IDE leerán comentarios con formatos especiales. Por ejemplo, la función "modeline" de Vim , que cambiaría su manejo de las pestañas mientras se edita una fuente con este comentario incluido cerca de la parte superior del archivo:
# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4
A veces, los programadores añaden comentarios como una forma de aliviar el estrés al comentar sobre herramientas de desarrollo, competidores, empleadores, condiciones de trabajo o la calidad del código en sí. [24] La aparición de este fenómeno se puede ver fácilmente en los recursos en línea que rastrean las blasfemias en el código fuente. [25]
Existen diversas visiones normativas y opiniones de larga data con respecto al uso adecuado de los comentarios en el código fuente. [26] [27] Algunas de ellas son informales y se basan en preferencias personales, mientras que otras se publican o promulgan como pautas formales para una comunidad en particular. [28]
Los expertos tienen diferentes puntos de vista sobre si los comentarios son apropiados en el código fuente y cuándo hacerlo. [9] [29] Algunos afirman que el código fuente debe escribirse con pocos comentarios, sobre la base de que el código fuente debe ser autoexplicativo o autodocumentado . [9] Otros sugieren que el código debe ser ampliamente comentado (no es raro que más del 50% de los caracteres que no son espacios en blanco en el código fuente estén contenidos en comentarios). [30] [31]
Entre estos puntos de vista está la afirmación de que los comentarios no son ni beneficiosos ni perjudiciales por sí mismos, y lo que importa es que sean correctos y se mantengan sincronizados con el código fuente, y se omitan si son superfluos, excesivos, difíciles de mantener o de otro modo inútiles. [32] [33]
En ocasiones, los comentarios se utilizan para documentar contratos en el enfoque de programación de diseño por contrato .
Dependiendo del público objetivo del código y otras consideraciones, el nivel de detalle y descripción puede variar considerablemente.
Por ejemplo, el siguiente comentario sobre Java sería adecuado en un texto introductorio diseñado para enseñar programación inicial:
String s = "Wikipedia" ; /* Asigna el valor "Wikipedia" a la variable s. */ Sin embargo, este nivel de detalle no sería apropiado en el contexto de código de producción u otras situaciones que involucren a desarrolladores experimentados. Estas descripciones rudimentarias son incompatibles con la directriz: "Los buenos comentarios... aclaran la intención". [10] Además, para los entornos de codificación profesionales, el nivel de detalle suele estar bien definido para cumplir con un requisito de rendimiento específico definido por las operaciones comerciales. [31]
Existen muchas alternativas estilísticas disponibles a la hora de considerar cómo deben aparecer los comentarios en el código fuente. En el caso de proyectos más grandes que involucran a un equipo de desarrolladores, los estilos de comentarios se acuerdan antes de comenzar el proyecto o evolucionan como una cuestión de convención o necesidad a medida que el proyecto crece. Por lo general, los programadores prefieren estilos que sean consistentes, no obstructivos, fáciles de modificar y difíciles de romper. [34]
Los siguientes fragmentos de código en C demuestran sólo un pequeño ejemplo de cómo los comentarios pueden variar estilísticamente, sin dejar de transmitir la misma información básica:
/* Este es el cuerpo del comentario. Variación uno. *//***************************\ * * * Este es el cuerpo del comentario. * * Variación dos. * * * \***************************/Factores como las preferencias personales, la flexibilidad de las herramientas de programación y otras consideraciones tienden a influir en las variantes estilísticas utilizadas en el código fuente. Por ejemplo, la Variación Dos podría no ser la preferida por los programadores que no tienen editores de código fuente que puedan automatizar la alineación y la apariencia visual del texto en los comentarios.
El consultor de software y comentarista tecnológico Allen Holub [35] es un experto que aboga por alinear los bordes izquierdos de los comentarios: [36]
/* Este es el estilo recomendado por Holub para C y C++. * Se demuestra en ''Enough Rope'', en la regla 29. */ /* Esta es otra forma de hacerlo, también en C. ** Es más fácil hacerlo en editores que no sangran automáticamente las segundas ** hasta las últimas líneas del comentario con un espacio desde la primera. ** También se usa en el libro de Holub, en la regla 31. */El uso de /* y */ como delimitadores de comentarios de bloque fue heredado de PL/I en el lenguaje de programación B, el predecesor inmediato del lenguaje de programación C. [37]
Los comentarios de línea generalmente utilizan un delimitador arbitrario o una secuencia de tokens para indicar el comienzo de un comentario y un carácter de nueva línea para indicar el final de un comentario.
En este ejemplo, se ignora todo el texto desde los caracteres ASCII // hasta el final de la línea.
// ------------------------- // Este es el cuerpo del comentario. // -------------------------A menudo, un comentario de este tipo debe comenzar en el extremo izquierdo y extenderse a toda la línea. Sin embargo, en muchos lenguajes, también es posible poner un comentario en línea con una línea de comandos, para agregarle un comentario, como en este ejemplo de Perl:
print $s . "\n" ; # Agrega un carácter de nueva línea después de imprimir Si un lenguaje permite tanto comentarios de línea como comentarios de bloque, los equipos de programación pueden decidir una convención para usarlos de manera diferente: por ejemplo, comentarios de línea solo para comentarios menores y comentarios de bloque para describir abstracciones de nivel superior.
Los programadores pueden usar etiquetas informales en los comentarios para ayudar a indexar problemas comunes. Luego, es posible buscarlas con herramientas de programación comunes, como la utilidad grep de Unix o incluso resaltarlas con sintaxis dentro de editores de texto . A veces se las denomina "etiquetas de código" [38] [39] o "tokens", y las herramientas de desarrollo pueden incluso ayudarlo a enumerarlas todas. [40]
Estas etiquetas varían ampliamente, pero pueden incluir:
Las convenciones tipográficas para especificar comentarios varían ampliamente. Además, los lenguajes de programación individuales a veces ofrecen variantes únicas.
El lenguaje de programación Ada utiliza '--' para indicar un comentario hasta el final de la línea.
Por ejemplo:
-- la tarea del controlador de tráfico aéreo toma solicitudes de despegue y aterrizaje tipo de tarea Controlador ( Mi_Pista : Runway_Access ) es -- entradas de tarea para el paso de mensajes sincrónicos entrada Solicitud_Despegue ( ID : en Avión_ID ; Despegue : fuera Runway_Access ); entrada Solicitud_Aproximación ( ID : en Avión_ID ; Aproximación : fuera Runway_Access ); fin Controlador ; APL utiliza ⍝para indicar un comentario hasta el final de la línea.
Por ejemplo:
⍝ Ahora sumamos los números: c ← a + b ⍝ suma En los dialectos que tienen los primitivos ⊣("izquierda") y ⊢("derecha"), los comentarios a menudo pueden estar dentro de declaraciones o separadas de ellas, en forma de cadenas ignoradas:
d ← 2 × c ⊣ 'donde' ⊢ c ← a + 'límite' ⊢ b Esta sección de código AppleScript muestra los dos estilos de comentarios utilizados en ese lenguaje.
(* Este programa muestra un saludo. *) en saludo ( myGreeting ) muestra el diálogo myGreeting y " mundo!" fin saludo-- Mostrar el saludo " Saludos " ( "Hola" )En este fragmento clásico de código BASIC temprano, se utiliza la palabra clave REM ( "Remark" ) para agregar comentarios.
10 REM Este programa BASIC muestra el uso de las sentencias PRINT y GOTO. 15 REM Llena la pantalla con la frase "HOLA" 20 PRINT "HOLA" 30 GOTO 20 En los BASIC de Microsoft posteriores , incluidos Quick Basic , Q Basic , Visual Basic , Visual Basic .NET y VB Script ; y en sus descendientes como FreeBASIC y Gambas, cualquier texto en una línea después de un carácter ' (apóstrofo) también se trata como un comentario.
Un ejemplo en Visual Basic .NET:
Clase pública Form1 Sub privada Button1_Click ( sender como objeto , e como EventArgs ) Maneja Button1 . Click ' El siguiente código se ejecuta cuando el usuario ' hace clic en el botón en la ventana del programa. Los comentarios rem aún existen. MessageBox . Show ( "Hola, mundo" ) 'Mostrar una ventana emergente con un saludo Fin Sub Fin Clase Este fragmento de código C demuestra el uso de un comentario de prólogo o "comentario de bloque" para describir el propósito de una declaración condicional . El comentario explica términos y conceptos clave e incluye una breve firma del programador que creó el código.
/* * Verificamos si hemos superado nuestro límite máximo de procesos, pero asegúrate de * excluir a root. Esto es necesario para que sea posible que login y * amigos establezcan el límite de procesos por usuario en algo menor * que la cantidad de procesos que root está ejecutando. -- Rik */ if ( atomic_read ( & p -> user -> processes ) >= p -> rlim [ RLIMIT_NPROC ]. rlim_cur && ! able ( CAP_SYS_ADMIN ) && ! able ( CAP_SYS_RESOURCE )) goto bad_fork_free ; Desde C99, también es posible utilizar la sintaxis // de C++, que indica un comentario de una sola línea.
La disponibilidad de comentarios de bloque permite marcar rupturas estructurales, es decir, violaciones admisibles de la regla de entrada única/salida única de la Programación Estructurada , de forma visible, como en el siguiente ejemplo:
static Edge edge_any ( Nodo n , Nodo m ) { // Devuelve si hay algún borde entre los nodos $n y $m. Edge e ; for ( e = n -> edges ; e ; e = e -> next ) { if ( e -> dst == m ) { /*********/ return e ; } } for ( e = m -> edges ; e ; e = e -> next ) { if ( e -> dst == n ) { /*****/ break ; } } return e ; } En muchos lenguajes que carecen de un comentario de bloque, por ejemplo awk , puedes usar secuencias de separadores de sentencias como ;en su lugar. Pero es imposible en lenguajes que usan la sangría como una indicación rígida de la estructura de bloque deseada, como Python .
El signo de exclamación ( ! ) se puede utilizar para marcar comentarios en el modo de configuración de un enrutador Cisco, sin embargo, dichos comentarios no se guardan en la memoria no volátil (que contiene la configuración de inicio), ni se muestran mediante el comando "show run". [41] [42]
Es posible insertar contenido legible por humanos que en realidad es parte de la configuración y puede guardarse en la configuración de inicio NVRAM a través de:
Pegue el texto a continuación para redirigir el tráfico manualmenteconfiguración tentero gi0/2No cerrarruta ip 0.0.0.0 0.0.0.0 gi0/2 nombre ISP2sin ruta ip 0.0.0.0 0.0.0.0 gi0/1 nombre ISP1entero gi0/1cerrarsalidaColdFusion utiliza comentarios similares a los comentarios HTML , pero en lugar de dos guiones, utiliza tres. Estos comentarios son capturados por el motor ColdFusion y no se imprimen en el navegador.
Estos comentarios se pueden anidar.
<!--- Esto imprime "Hola mundo" en el navegador. <!--- Este es un comentario utilizado dentro del primero. ---> ---> <cfoutput> Hola mundo < br /> </cfoutput>D utiliza comentarios de estilo C++, así como comentarios multilínea anidados de estilo D, que comienzan con '/+' y terminan con '+/'.
// Este es un comentario de una sola línea. /* Este es un comentario de varias líneas.*/ /+ Este es un comentario anidado +/Este fragmento de código Fortran IV demuestra cómo se utilizan los comentarios en ese lenguaje, que está muy orientado a las columnas. Una letra "C" en la columna 1 hace que toda la línea se considere un comentario.
C C Las líneas que comienzan con 'C' (en la primera columna o 'comentario') son comentarios C WRITE ( 6 , 610 ) 610 FORMAT ( 12 H HOLA MUNDO ) END Tenga en cuenta que las columnas de una línea se tratan como cuatro campos: 1 a 5 es el campo de etiqueta, 6 hace que la línea se tome como una continuación de la declaración anterior; y las declaraciones y declaraciones van del 7 al 72.
Este fragmento de código Fortran demuestra cómo se utilizan los comentarios en ese lenguaje, y los comentarios en sí mismos describen las reglas básicas de formato.
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! * Todos los caracteres después de un signo de exclamación se consideran comentarios * ! * * ... Los comentarios de línea en Haskell comienzan con '--' (dos guiones) hasta el final de la línea, y los comentarios de varias líneas comienzan con '{-' y terminan con '-}'.
{- este es un comentario en más líneas -} -- y este es un comentario en una línea putStrLn "Wikipedia" -- este es otro comentario Haskell también proporciona un método de programación para comentar, conocido como "Bird Style". [43] En este, todas las líneas que comienzan con > se interpretan como código, todo lo demás se considera un comentario. Un requisito adicional es que siempre se debe dejar una línea en blanco antes y después del bloque de código:
En el estilo Bird debes dejar un espacio en blanco antes del código.> hecho :: Entero -> Entero > hecho 0 = 1 > hecho ( n + 1 ) = ( n + 1 ) * hecho n Y también debes dejar una línea en blanco después del código.La programación literaria también se puede realizar en Haskell, utilizando LaTeX . El entorno de código se puede utilizar en lugar del estilo de Richard Bird: En el estilo LaTeX esto es equivalente al ejemplo anterior, el entorno de código se podría definir en el preámbulo de LaTeX. Aquí hay una definición simple:
\usepackage { textualmente } \newenvironment { código }{ \verbatim }{ \endverbatim }Más tarde en
% el archivo fuente de LaTeX
La llamada a la función \verb |fact n| calcula $ n ! $ si $ n \ge 0 $ , aquí hay una definición: \\ \begin { code } fact :: Integer -> Integer fact 0 = 1 fact ( n + 1 ) = ( n + 1 ) * fact n \end { code }
Aquí hay más explicaciones usando el marcado \LaTeX {} Este fragmento de código Java muestra un comentario de bloque utilizado para describir el setToolTipTextmétodo. El formato es coherente con los estándares Javadoc de Sun Microsystems . El comentario está diseñado para que lo lea el procesador Javadoc.
/** * Este es un comentario de bloque en Java. * El método setToolTipText registra el texto que se mostrará en la información sobre herramientas. * El texto se muestra cuando el cursor permanece sobre el componente. * * @param text La cadena que se mostrará. Si 'text' es nulo, * la información sobre herramientas se desactiva para este componente. */ public void setToolTipText ( String text ) { // Este es un comentario en línea en Java. TODO: Escribir código para este método. } JavaScript utiliza // para preceder a los comentarios y /* */ para comentarios de varias líneas.
// Un comentario de JavaScript de una sola línea var iNum = 100 ; var iTwo = 2 ; // Un comentario al final de la línea /* comentario de JavaScript de varias líneas */ El lenguaje de programación Lua utiliza guiones dobles, --, para comentarios de una sola línea de manera similar a los lenguajes Ada , Eiffel , Haskell , SQL y VHDL . Lua también tiene comentarios en bloque, que comienzan con --[[y se ejecutan hasta un cierre.]]
Por ejemplo:
--[[Un comentario de varias líneas ]] print ( 20 ) -- imprime el resultadoUna técnica común para comentar un fragmento de código, [44] es encerrar el código entre --[[y --]], como se muestra a continuación:
--[[ print(10) --]] -- sin acción (comentado)En este caso, es posible reactivar el código agregando un solo guión a la primera línea:
---[[ imprimir ( 10 ) --]] --> 10En el primer ejemplo, el --[[de la primera línea inicia un comentario largo y los dos guiones de la última línea siguen estando dentro de ese comentario. En el segundo ejemplo, la secuencia ---[[inicia un comentario normal de una sola línea, de modo que la primera y la última línea se convierten en comentarios independientes. En este caso, el printestá fuera de los comentarios. En este caso, la última línea se convierte en un comentario independiente, ya que comienza con --.
Los comentarios largos en Lua pueden ser más complejos que estos, como puedes leer en la sección llamada "Cadenas largas" cf Programación en Lua .
En el lenguaje de programación MATLAB , el carácter '%' indica un comentario de una sola línea. Los comentarios de varias líneas también están disponibles mediante corchetes %{ y %} y pueden estar anidados, por ejemplo
% Estas son las derivadas para cada término d = [ 0 - 1 0 ]; %{ %{ (Ejemplo de un comentario anidado, la sangría es cosmética (y se ignora).) %} Formamos la secuencia , siguiendo la fórmula de Taylor . Nótese que estamos operando sobre un vector . %} seq = d .* ( x - c ) .^ n ./ ( factorial ( n ) ) % Sumamos para obtener la aproximación de Taylor aprox = suma ( seq ) Nim utiliza el carácter '#' para los comentarios en línea. Los comentarios de bloques de varias líneas se abren con '#[' y se cierran con ']#'. Los comentarios de bloques de varias líneas se pueden anidar.
Nim también tiene comentarios de documentación que utilizan marcados mixtos Markdown y ReStructuredText . Los comentarios de documentación en línea utilizan '##' y los comentarios de documentación de bloques de varias líneas se abren con '##[' y se cierran con ']##'. El compilador puede generar documentación HTML , LaTeX y JSON a partir de los comentarios de documentación. Los comentarios de documentación son parte del árbol de sintaxis abstracta y se pueden extraer mediante macros. [45]
## Documentación del módulo *ReSTructuredText* y **MarkDown** # Este es un comentario, pero no es un comentario de documentación.tipo Kitten = object ## Documentación del tipo age : int ## Documentación del campo proc purr ( self : Kitten ) = ## Documentación de la función echo "Purr Purr" # Este es un comentario, pero no es un comentario de documentación. # Este es un comentario, pero no es un comentario de documentación.OCaml utiliza comentarios anidables, lo que resulta útil al comentar un bloque de código.
codeLine (*nivel de comentario 1(*nivel de comentario 2*)*)En Pascal y Delphi , los comentarios están delimitados por '{ ... }'. Las líneas de comentario también pueden comenzar con '\\'. Como alternativa, para las computadoras que no admiten estos caracteres, se permiten '(* ... *)'. [46]
En la familia de lenguajes más moderna de Niklaus Wirth (incluidos Modula-2 y Oberon ), los comentarios están delimitados por '(* ... *)'. [47] [48]
Por ejemplo:
(* diagonales de prueba *) columnDifference := testColumn - columna ; si ( fila + columnDifference = testRow ) o ....... Los comentarios se pueden anidar. // se pueden incluir en un {} y {} se pueden incluir en un (**).
Los comentarios de línea en Perl y muchos otros lenguajes de programación comienzan con un símbolo numeral (#).
# Un ejemplo simple # my $s = "Wikipedia" ; # Establece la variable s en "Wikipedia". print $s . "\n" ; # Agrega un carácter de nueva línea después de imprimir En lugar de una construcción de comentarios de bloque regular, Perl utiliza Plain Old Documentation , un lenguaje de marcado para programación literaria , [49] por ejemplo: [50]
=item Pod::Lista-E<gt>nuevo()Crea un nuevo objeto de lista. Las propiedades se pueden especificar mediante una referencia hash como la siguiente: mi $lista = Pod::List->new({ -start => $., -indent => 4 });Consulte los métodos/propiedades individuales para obtener más detalles.=cortarsub nuevo { mi $this = shift ; mi $class = ref ( $this ) || $this ; mi %params = @_ ; mi $self = { %params }; bendecir $self , $class ; $self -> inicializar (); devolver $self ; } R solo admite comentarios en línea iniciados por el carácter almohadilla (#).
# Este es un comentario print ( "Esto no es un comentario" ) # Este es otro comentario Raku (anteriormente llamado Perl 6) utiliza los mismos comentarios de línea y comentarios de documentación POD que Perl normal (ver la sección Perl más arriba), pero agrega un tipo de comentario de bloque configurable: "comentarios multilínea/incrustados". [51]
Estos comienzan con un carácter almohadilla, seguido de una comilla invertida y luego algún carácter de corchete de apertura, y terminan con el carácter de corchete de cierre correspondiente. [51] El contenido no solo puede abarcar varias líneas, sino que también puede estar incrustado en línea.
#`{{ "comentando" esta versión toggle-case(Str:D $s)Alterna entre mayúsculas y minúsculas de cada carácter en una cadena: mi Str $toggled-string = toggle-case("¡MI NOMBRE ES MICHAEL!");}}sub toggle-case ( Str:D $s ) #`( esta versión de paréntesis se usa ahora ) { ...}Los comentarios en PHP pueden ser en estilo C++ (tanto en línea como en bloque) o utilizar hashes. PHPDoc es un estilo adaptado de Javadoc y es un estándar común para documentar código PHP.
A partir de PHP 8, el signo # solo puede significar un comentario si no va seguido inmediatamente de '['. De lo contrario, significará un atributo de función, que se ejecuta hasta ']':
/** * Esta clase contiene una documentación de muestra. * * @author Unknown */ #[ Attribute ] class MyAttribute { const VALUE = 'value' ; // Este es un comentario en línea. Comienza con '//', como en C++. private $value ; # Este es un comentario en línea de estilo Unix, que comienza con '#'. public function __construct ( $value = null ) { $this -> value = $value ; } /* Este es un comentario de varias líneas. Estos comentarios no se pueden anidar. */}Comentarios en Windows PowerShell
# Comentario de una sola línea Write-Host "¡Hola, mundo!"<# Comentario de varias líneas #>Write-Host "¡Adiós, mundo!"Los comentarios en línea en Python utilizan el carácter almohadilla (#), como en los dos ejemplos de este código:
# Este programa imprime "Hola mundo" en la pantalla de impresión ( "¡Hola mundo!" ) # Tenga en cuenta la nueva sintaxisLos comentarios en bloque, tal como se definen en este artículo, técnicamente no existen en Python. [52] Se puede utilizar una cadena literal simple representada por una cadena entre comillas triples, [53] pero el intérprete no la ignora de la misma manera que el comentario "#". [52] En los ejemplos siguientes, las cadenas entre comillas triples actúan de esta manera como comentarios, pero también se tratan como cadenas de documentación :
""" Suponiendo que se trata del archivo mymodule.py, entonces esta cadena, al ser la primera declaración del archivo, se convertirá en la cadena de documentación del módulo "mymodule" cuando se importe el archivo. """clase MyClass : """La cadena de documentación de la clase""" def my_method ( self ): """La cadena de documentación del método""" def my_function (): """La cadena de documentación de la función""" Los comentarios en línea en Ruby comienzan con el carácter #.
Para crear un comentario de varias líneas, se debe colocar "=begin" al comienzo de una línea y, a continuación, se ignora todo lo que comience una línea hasta "=end". Incluir un espacio después del signo igual en este caso genera un error de sintaxis.
pone "Esto no es un comentario" # esto es un comentariopone "Esto no es un comentario" =comenzarLo que sea que vaya en estas líneasEs solo para el lector humano.=finpone "Esto no es un comentario" Los comentarios estándar en SQL tienen un formato de una sola línea y utilizan dos guiones:
-- Este es un comentario de una sola línea -- seguido de una segunda línea SELECT COUNT ( * ) FROM Authors WHERE Authors . name = 'Smith' ; -- Nota: solo queremos 'smith' -- este comentario aparece después del código SQL Como alternativa, Transact-SQL , MySQL , SQLite , PostgreSQL y Oracle admiten una sintaxis de formato de comentario idéntica al estilo de "comentario en bloque" utilizado en la sintaxis para C y Java . [54] [55] [56] [57] [58]
MySQL también admite comentarios desde el carácter almohadilla (#) hasta el final de la línea.
Los comentarios de una sola línea comienzan con dos barras diagonales (//):
//Esto es un comentario.Los comentarios de varias líneas comienzan con una barra diagonal seguida de un asterisco (/*) y terminan con un asterisco seguido de una barra diagonal (*/):
/* Esto también es un comentario pero está escrito en varias líneas. */Los comentarios multilineales en Swift se pueden anidar dentro de otros comentarios multilineales. Para escribir comentarios anidados, se inicia un bloque de comentario multilineal y luego se inicia un segundo comentario multilineal dentro del primer bloque. Luego se cierra el segundo bloque, seguido del primer bloque:
/* Este es el comienzo del primer comentario multilínea. /* Este es el segundo comentario multilínea anidado. */ Este es el final del primer comentario multilínea. */Los comentarios en XML (o HTML) se introducen con
< !--y puede extenderse por varias líneas hasta el terminador,
-->Por ejemplo,
<!-- seleccione el contexto aquí --> <param name= "context" value= "public" /> Para compatibilidad con SGML , la cadena "--" (doble guión) no está permitida dentro de los comentarios.
En los lenguajes interpretados, los comentarios son visibles para el usuario final del programa. En algunos casos, como en el caso de las secciones de código que están "comentadas", esto puede presentar una vulnerabilidad de seguridad . [59]
Las comillas triples se tratan como cadenas normales con la excepción de que pueden abarcar varias líneas. Por cadenas normales me refiero a que si no se asignan a una variable, se recolectarán inmediatamente como basura tan pronto como se ejecute ese código. Por lo tanto, el intérprete no las ignora de la misma manera que el comentario #a.