En programación de computadoras , un comentario es una explicación o anotación legible por el programador en el código fuente de un programa de computadora . 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 formas para generar documentación externa al código fuente en sí 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 proporcionada por los comentarios permite un amplio grado de variabilidad, pero las convenciones formales para su uso suelen formar parte de las guías de estilo de programación.
Descripción general
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 de 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 final . Algunos lenguajes de programación (como MATLAB ) permiten que los comentarios de bloque se aniden recursivamente unos dentro de otros, pero otros (como Java ) no. [4] [5] [6]
Los comentarios de línea comienzan con un delimitador de comentarios 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 caracteres) en el código fuente y continúan hasta el final de la línea. [6]
Algunos lenguajes de programación emplean comentarios en bloque y en 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 idiomas 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]
Usos
La mejor forma de utilizar los comentarios está sujeta a disputas; diferentes comentaristas han ofrecido puntos de vista variados y en ocasiones opuestos. [7] [8] Hay muchas formas diferentes de escribir comentarios y muchos comentaristas ofrecen consejos contradictorios. [8]
Planificación y revisión
Los comentarios se pueden utilizar como una forma de pseudocódigo para delinear la intención antes de escribir el código real. En este caso, debería explicar la lógica detrás del código en lugar del código en sí. .
/ * recorrer todos los elementos devueltos por el servidor (deben procesarse cronológicamente) * / for ( i = ( numElementsReturned - 1 ); i > = 0 ; i - ) { / * procesar los datos de cada elemento * / updatePattern ( i , elementos devueltos [ 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.
Descripción del código
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 debe reescribirse, o de que el nombre es incorrecto.
- "No documente el código incorrecto, vuelva a escribirlo". [9]
- "Los buenos comentarios no repiten el código ni lo explican. Aclaran su intención. Los comentarios deberían explicar, en un nivel de abstracción más alto que el código, lo que está tratando de hacer". [10]
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 en la corrección de errores. Por ejemplo:
'La segunda variable se atenúa debido a los errores del servidor producidos cuando se reutilizan los datos del formulario. No hay documentación disponible sobre el problema del comportamiento del servidor, así que solo codifique. vtx = servidor . mappath ( "configuración local" )
Descripción algorítmica
A veces, el código fuente contiene una solución novedosa o digna de mención a un problema específico. En tales casos, los comentarios pueden contener una explicación de la metodología. Tales explicaciones pueden incluir diagramas y demostraciones matemáticas formales. Esto puede constituir una explicación del código, más que una aclaración de su intención; pero otros encargados de mantener la base del código pueden encontrar esa explicación crucial. Esto podría ser especialmente cierto en el caso de dominios de problemas altamente especializados; o optimizaciones, construcciones o llamadas a funciones de uso poco frecuente. [11]
Por ejemplo, un programador puede agregar un comentario para explicar por qué se eligió una ordenación por inserción en lugar de una ordenación rápida , ya que la primera es, en teoría, más lenta que la segunda. Esto podría escribirse de la siguiente manera:
lista = [ f ( b ), f ( b ), f ( c ), f ( d ), f ( a ), ... ] ; // Necesita un tipo estable. Además, el rendimiento realmente no importa. insertion_sort ( lista );
Inclusión de recursos
Los logotipos , diagramas y diagramas de flujo que constan de construcciones artísticas ASCII se pueden insertar en el código fuente formateado como comentario. [12] Además, los avisos de derechos de autor pueden incorporarse en el 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, por lo general, se relega a archivos de recursos externos.
El siguiente fragmento de código es un diagrama ASCII simple que muestra el flujo de proceso para un script de administración del sistema contenido en un archivo de script de Windows que se ejecuta en Windows Script Host . Aunque una sección que marca el código aparece como comentario, el diagrama en sí aparece en una sección XML CDATA , que técnicamente se considera distinta de los comentarios, pero que puede tener propósitos similares. [13]
id = "ProcessDiagram000" > HostApp (Main_process) | V script.wsf (app_cmd) -> ClientApp (async_run, batch_process) | | V mru.ini (mru_history) ]]>
Aunque este diagrama idéntico podría haberse incluido fácilmente como comentario, el ejemplo ilustra un caso en el que un programador puede optar por no utilizar comentarios como una forma de incluir recursos en el código fuente. [13]
Metadatos
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 del 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 del programa hasta ahora , la URL de la documentación sobre cómo utilizar 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 en un libro u otra referencia, los comentarios pueden usarse para dar el número de página y el título del libro o Solicitud de comentarios u otra referencia.
Depuración
Una práctica común de 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 ciertos fragmentos de código del programa final, o (más comúnmente) se puede usar para encontrar la fuente de un error. Al comentar sistemáticamente y ejecutar partes del programa, se puede determinar la fuente de un error, lo que permite corregirlo.
A continuación, se muestra un ejemplo de código de comentario con fines de exclusión:
if ( opt . es igual a ( "e" )) opt_enabled = true ; / * if (opt.equals ("d")) opt_debug = true; * / if ( opt . es igual a ( "v" )) opt_verbose = true ;
El fragmento de código anterior sugiere que el programador optó por deshabilitar la opción de depuración por alguna razón.
Muchos IDE permiten agregar o eliminar rápidamente dichos comentarios con opciones de menú únicas o combinaciones de teclas. El programador solo tiene que marcar la parte del texto que desea (des) comentar y elegir la opción adecuada.
Generación automática de documentación
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]
Ejemplos de generadores de documentación incluyen los programas Javadoc para usar con Java , Ddoc para D , Doxygen para C , C ++ , Java, IDL , Visual Expert para PL / SQL , Transact-SQL , PowerBuilder y PHPDoc para PHP . Las formas 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]
Extensión de sintaxis
Ocasionalmente, los elementos de sintaxis que originalmente estaban destinados a ser comentarios se vuelven a utilizar para transmitir información adicional a un programa, como " comentarios condicionales ". Estos "comentarios candentes" pueden ser la única solución práctica que mantiene la compatibilidad con versiones anteriores, pero en general se consideran una tontería . [20]
Usos de la directiva
Hay casos en los que se cooptan los caracteres de comentario normales para crear una directiva especial para un editor o intérprete.
Dos ejemplos de esto dirigiendo a un intérprete son:
- El " shebang " de Unix -
#!
- utilizado en la primera línea de una secuencia de comandos para señalar el intérprete que se utilizará. - "Comentarios mágicos" que identifican la codificación que utiliza un archivo fuente, [21] por ejemplo, PEP 263 de Python. [22]
El siguiente script para un sistema similar a Unix muestra estos dos 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 una "falla" predeterminada en una declaración de caso :
cambiar ( comando ) { caso CMD_SHOW_HELP_AND_EXIT : do_show_help (); / * Fall hasta * / case CMD_EXIT : do_exit (); romper ; case CMD_OTHER : do_other (); 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 de gcc comenzó a buscar estas (u otras indicaciones de intención deliberada) y, si no se encuentra, emitir: "advertencia: esta declaración puede fallar" . [23]
Muchos editores e IDE leerán comentarios con formato especial. Por ejemplo, la función "modeline" de Vim ; que cambiaría su manejo de pestañas al editar una fuente con este comentario incluido cerca de la parte superior del archivo:
# vim: tabstop = 8 expandtab shiftwidth = 4 softtabstop = 4
El alivio del estrés
A veces, los programadores agregarán 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 ocurrencia de este fenómeno se puede ver fácilmente en los recursos en línea que rastrean las malas palabras en el código fuente. [25]
Puntos de vista normativos
Hay varios puntos de vista normativos y opiniones de larga data con respecto al uso adecuado de los comentarios en el código fuente. [26] [27] Algunos de estos son informales y se basan en preferencias personales, mientras que otros se publican o promulgan como pautas formales para una comunidad en particular. [28]
Necesidad de comentarios
Los expertos tienen diferentes puntos de vista sobre si los comentarios son apropiados en el código fuente y cuándo. [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 comentado extensamente (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 los comentarios). [30] [31]
Entre estas opiniones 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 que se omitan si son superfluos, excesivos, difíciles de mantener o inútiles. [32] [33]
En ocasiones, los comentarios se utilizan para documentar los contratos en el enfoque de diseño por contrato de la programación.
Nivel de detalle
Según la audiencia a la que se destina el código y otras consideraciones, el nivel de detalle y descripción puede variar considerablemente.
Por ejemplo, el siguiente comentario de 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 del código de producción u otras situaciones que involucren a desarrolladores experimentados. Tales descripciones rudimentarias son inconsistentes con la directriz: "Buenos comentarios ... aclaran la intención". [10] Además, para entornos de codificación profesionales, el nivel de detalle normalmente está bien definido para cumplir con un requisito de rendimiento específico definido por las operaciones comerciales. [31]
Estilos
Hay muchas alternativas de estilo disponibles al considerar cómo deberían aparecer los comentarios en el código fuente. Para proyectos más grandes que involucran a un equipo de desarrolladores, los estilos de comentarios se acuerdan antes de que comience un 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]
Bloquear comentario
Los siguientes fragmentos de código en C demuestran solo 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 ser desfavorecida entre 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 de tecnología 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 de hacer en editores que no sangran automáticamente desde la segunda ** hasta la última línea del comentario 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 se heredó de PL / I en el lenguaje de programación B, el predecesor inmediato del lenguaje de programación C. [37]
Comentarios de línea
Los comentarios de línea generalmente usan 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, este comentario tiene que comenzar en el extremo izquierdo y extenderse a toda la línea. Sin embargo, en muchos idiomas, también es posible poner un comentario en línea con una línea de comando, para agregarle un comentario, como en este ejemplo de Perl:
imprimir $ s . "\ n" ; # Agregue 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 sobre 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.
Etiquetas
Los programadores pueden usar etiquetas informales en los comentarios para ayudar a indexar problemas comunes. A continuación, es posible que se puedan buscar con herramientas de programación comunes, como la utilidad grep de Unix o incluso resaltadas por sintaxis dentro de los editores de texto . A veces se les denomina "etiquetas de código" [38] [39] o "tokens". [40]
Dichas etiquetas difieren ampliamente, pero pueden incluir:
- ERROR: un error conocido que debe corregirse.
- FIXME: debe corregirse.
- HACK: una solución alternativa.
- TODO - algo por hacer.
- DESHECHO: una inversión o "retroceso" del código anterior.
- XXX: advierte a otros programadores sobre códigos problemáticos o erróneos
Ejemplos de
Comparación
Las convenciones tipográficas para especificar comentarios varían ampliamente. Además, los lenguajes de programación individuales a veces proporcionan variantes únicas. Para una revisión detallada, consulte el artículo de comparación de lenguajes de programación .
Ada
El lenguaje de programación Ada usa '-' para indicar un comentario hasta el final de la línea.
Por ejemplo:
- la tarea del controlador de tránsito aéreo toma solicitudes de despegue y aterrizaje tipo de tarea Controlador ( My_Runway : Runway_Access ) es - entradas de tarea para la entrada de paso de mensajes síncronos Request_Takeoff ( ID : en Airplane_ID ; Despegue : out Runway_Access ); entrada Request_Approach ( ID : en Airplane_ID ; Aproximación : fuera de Runway_Access ); controlador final ;
APL
APL utiliza ⍝
para indicar un comentario hasta el final de la línea.
Por ejemplo:
⍝ Ahora suma los números: c ← a + b ⍝ suma
En los dialectos que tienen las primitivas ⊣
("izquierda") y ⊢
("derecha"), los comentarios a menudo pueden estar dentro o en declaraciones separadas, en forma de cadenas ignoradas:
d ← 2 × c ⊣ 'donde' ⊢ c ← a + 'límite' ⊢ b
AppleScript
Esta sección del código AppleScript muestra los dos estilos de comentarios utilizados en ese lenguaje.
(* Este programa muestra un saludo. *) En greet ( myGreeting ) muestra el cuadro de diálogo myGreeting & "world!" saludar al final - Muestra el saludo de saludo ( "Hola" )
BÁSICO
En este clásico fragmento de código BASIC temprano, la palabra clave REM ( "Observación" ) se usa para agregar comentarios.
10 REM Este programa BÁSICO muestra el uso de las instrucciones PRINT y GOTO. 15 REM Llena la pantalla con la frase "HOLA" 20 IMPRIMIR "HOLA" 30 GOTO 20
En Microsoft BASIC posteriores , incluidos Quick Basic , Q Basic , Visual Basic , Visual Basic .NET y VB Script ; y en descendientes como FreeBASIC y Gambas, cualquier texto en una línea después de un carácter '(apóstrofe) también se trata como un comentario.
Un ejemplo en Visual Basic .NET:
Public Class Form1 Private Sub Button1_Click ( remitente como objeto , e como EventArgs ) Maneja Button1 . Haga clic en 'El siguiente código se ejecuta cuando el usuario ' hace clic en el botón en la ventana del programa. Los comentarios rem todavía existen. MessageBox . Show ( "Hello, World" ) 'Muestra una ventana emergente con un saludo End Sub End Class
C
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.
/ * * Verifique si estamos por encima de nuestro límite máximo de proceso, pero asegúrese de * excluir root. Esto es necesario para que sea posible que el inicio de sesión y * amigos establezcan el límite de proceso por usuario en algo más bajo * que la cantidad de procesos que está ejecutando root. - Rik * / if ( atomic_read ( & p -> usuario -> procesos ) > = p -> rlim [ RLIMIT_NPROC ]. Rlim_cur && ! Capaz ( CAP_SYS_ADMIN ) && ! Capaz ( CAP_SYS_RESOURCE )) goto bad_fork_free ;
Desde C99, también ha sido posible utilizar la sintaxis // de C ++, que indica un comentario de una sola línea.
Configuración de Cisco IOS e IOS-XE
El signo de exclamación ( ! ) Se puede usar 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 se puede guardar en la configuración de inicio de NVRAM a través de:
- El comando "descripción", utilizado para agregar una descripción a la configuración de una interfaz o de un vecino BGP
- El parámetro "nombre", para agregar un comentario a una ruta estática
- El comando "comentario" en las listas de acceso
! Pegue el texto a continuación para redirigir el tráfico manualmenteconfig tint gi0 / 2no cierraruta 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 ISP1int gi0 / 1cerradoSalida
Fusión fría
ColdFusion usa comentarios similares a los comentarios HTML , pero en lugar de dos guiones, usa tres. Estos comentarios son capturados por el motor ColdFusion y no se imprimen en el navegador.
---> Hello World < br />
Fortran IV
Este fragmento de código de Fortran IV demuestra cómo se utilizan los comentarios en ese lenguaje, que está muy orientado a columnas. Una letra "C" en la columna 1 hace que toda la línea se trate como 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 HELLO WORLD ) 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.
Fortran 90
Este fragmento de código de Fortran demuestra cómo se usan los comentarios en ese lenguaje, y los comentarios mismos describen las reglas básicas de formato.
! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ! * Todos los caracteres después de un signo de exclamación se consideran comentarios * ! * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * programa comment_test print '(A)' , 'Hola mundo' ! Fortran 90 introdujo la opción de comentarios en línea. final del programa
Haskell
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 alfabetizado para comentar conocido como "Estilo pájaro". [43] En esto, 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 deje una línea en blanco antes y después del bloque de código:
En estilo Bird tienes que dejar un espacio en blanco antes del código.> hecho :: Entero -> Entero > hecho 0 = 1 > hecho ( n + 1 ) = ( n + 1 ) * hecho nY también debe dejar una línea en blanco después del código.
La programación alfabetizada también se puede hacer en Haskell, usando LaTeX . Se puede usar el entorno de código en lugar del estilo de Richard Bird: en el estilo LaTeX esto es equivalente al ejemplo anterior, el entorno de código podría definirse en el preámbulo de LaTeX. Aquí hay una definición simple:
\ usepackage { verbatim } \ newenvironment { código } { \ verbatim } { \ endverbatim }
más tarde
% el archivo fuente LaTeX
El \ verbo | hecho n | llamada de funció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í más explicación usando el marcado \ LaTeX {}
Java
Este fragmento de código Java muestra un comentario de bloque utilizado para describir el setToolTipText
método. El formato es coherente con los estándares Javadoc de Sun Microsystems . El comentario está diseñado para ser leído por el procesador Javadoc.
/ ** * Este es un comentario de bloque en Java. * El método setToolTipText registra el texto para mostrar en una información sobre herramientas. * El texto se muestra cuando el cursor permanece sobre el componente. * * @param text La cadena que se mostrará. Si 'texto' es nulo, * la información sobre herramientas está desactivada para este componente. * / public void setToolTipText ( String text ) { // Este es un comentario en línea en Java. TODO: escriba el código para este método. }
JavaScript
JavaScript usa // para preceder a los comentarios y / * * / para comentarios de varias líneas.
// Un comentario JavaScript de una sola línea var iNum = 100 ; var iTwo = 2 ; // Un comentario al final de la línea / * comentario JavaScript de varias líneas * /
Lua
El lenguaje de programación Lua utiliza guiones dobles --
, para comentarios de una sola línea de forma similar a los lenguajes Ada , Eiffel , Haskell , SQL y VHDL . Lua también tiene comentarios de bloque, que comienzan con --[[
y se ejecutan hasta un cierre]]
Por ejemplo:
- [[Un comentario largo de varias líneas ]] imprimir ( 20 ) - imprimir el resultado
Una 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 ) -]] -> 10
En el primer ejemplo, --[[
en la primera línea comienza un comentario largo y los dos guiones en la última línea todavía están dentro de ese comentario. En el segundo ejemplo, la secuencia ---[[
inicia un comentario ordinario de una sola línea, de modo que la primera y la última línea se convierten en comentarios independientes. En este caso, los print
comentarios son externos. 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 puede leer en la sección llamada "Cadenas largas" cf Programación en Lua .
MATLAB
En el lenguaje de programación de 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 se pueden anidar, p. Ej.
% Estos son los derivados para cada términod = [ 0 - 1 0 ]; % { % { (Ejemplo de un comentario anidado, la sangría es para cosméticos (y se ignora).) %} Nos formamos la secuencia , después de la Taylor fórmula . Nota que nos ' re operativo en un vector . %}seq = d . * ( x - c ) . ^ n ./ ( factorial ( n )) % Sumamos para obtener la aproximación de Tayloraprox = suma ( seq )
Nim
Nim usa 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 marcas mixtas de Markdown y ReStructuredText . Los comentarios de documentación en línea usan '##' 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 la documentación. Los comentarios de la documentación forman 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 un comentario de documentación.type Kitten = object ## Documentation of type age : int ## Documentation of fieldproc purr ( self : Kitten ) = ## Documentación de la función echo "Purr Purr" # Esto es un comentario, pero no es un comentario de documentación.# Esto es un comentario, pero no un comentario de documentación.
OCaml
OCaml usa comentarios encajables, lo cual es útil al comentar un bloque de código.
codeLine (* nivel de comentario 1 (* nivel de comentario 2 *) *)
Pascal
En la familia de idiomas pascal de Niklaus Wirth (incluidos Modula-2 y Oberon ), los comentarios se abren con '(*' y se completan con '*)'.
por ejemplo:
(* prueba de diagonales *) columnDifference : = testColumn - column ; if ( row + columnDifference = testRow ) o .......
En los dialectos modernos de Pascal, se usan '{' y '}' en su lugar. [46]
Perl
Los comentarios de línea en Perl y muchos otros lenguajes de programación comienzan con un símbolo de almohadilla (#).
# Un ejemplo simple # my $ s = "Wikipedia" ; # Establece la variable s en "Wikipedia". imprimir $ s . "\ n" ; # Agregue un carácter de nueva línea después de imprimir
En lugar de una construcción regular de comentarios en bloque, Perl usa Plain Old Documentation , un lenguaje de marcado para programación alfabetizada , [47] por ejemplo: [48]
= elemento Pod :: List-E nuevo () Crea un nuevo objeto de lista. Las propiedades se pueden especificar mediante una referencia hash como esta: my $ list = Pod :: List-> new ({-start => $., -indent => 4});Consulte los métodos / propiedades individuales para obtener más detalles.= cortarsub new { my $ this = shift ; mi $ clase = ref ( $ esto ) || $ esto ; my % params = @_ ; my $ self = { % params }; bendiga $ a sí mismo , $ clase ; $ self -> initialize (); return $ self ; }
R
R solo admite comentarios en línea iniciados por el carácter de almohadilla (#).
# Esto es un comentario imprimir ( "Esto no es un comentario" ) # Este es otro comentario
Raku
Raku (anteriormente llamado Perl 6) usa los mismos comentarios de línea y comentarios de documentación de POD que Perl normal (ver la sección de Perl anterior), pero agrega un tipo de comentario de bloque configurable: "comentarios multilínea / incrustados". [49]
Estos comienzan con un carácter de almohadilla, seguido de una tilde, y luego un carácter de corchetes de apertura, y terminan con el carácter de corchetes de cierre correspondiente. [49] El contenido no solo puede abarcar varias líneas, sino que también se puede incrustar en línea.
# `{{" comentando "esta versión cambiar-caso (Str: D $ s)Alterna el caso de cada carácter en una cadena: my Str $ toggled-string = toggle-case ("¡MI NOMBRE ES MICHAEL!");}}sub toggle-case ( Str: D $ s ) # `(esta versión de parens se usa ahora) { ...}
PHP
Los comentarios en PHP pueden estar en estilo C ++ (tanto en línea como en bloque) o usar hashes. PHPDoc es un estilo adaptado de Javadoc y es un estándar común para documentar código PHP.
Potencia Shell
Comentarios en Windows PowerShell
# Comentario de una sola línea Escribir-Anfitrión "¡Hola, mundo!"<# Comentario de varias líneas #>Escribe-Anfitrión "¡Adiós, mundo!"
Pitón
Los comentarios en línea en Python usan el carácter hash (#), como en los dos ejemplos de este código:
# Este programa imprime "Hola mundo" en la pantalla impresa ( "¡Hola mundo!" ) # Tenga en cuenta la nueva sintaxis
Los comentarios de bloque, como se definen en este artículo, no existen técnicamente en Python. [50] Se puede usar un literal de cadena simple representado por una cadena entre comillas triples, [51] pero el intérprete no lo ignora de la misma manera que el comentario "#". [50] En los ejemplos siguientes, las cadenas triples entre comillas dobles actúan de esta manera como comentarios, pero también se tratan como cadenas de documentos :
"" " Suponiendo que este es el archivo mymodule.py, esta cadena, que es la primera declaración del archivo, se convertirá en la cadena de documentos del módulo" mymodule " cuando se importe el archivo. " ""class MyClass : "" "La cadena de documentos de la clase" "" def my_method ( self ): "" "La cadena de documentos del método" ""def my_function (): "" "La cadena de documentos de la función" ""
Rubí
Comentarios en Ruby .
Comentarios de una sola línea: (la línea comienza con almohadilla "#")
pone "Esto no es un comentario"# esto es un comentariopone "Esto no es un comentario"
Comentarios de varias líneas: (los comentarios van entre las palabras clave "comienzo" y "final")
pone "Esto no es un comentario"= comenzarlo que sea que pase en estas líneases solo para el lector humano= finpone "Esto no es un comentario"
SQL
Los comentarios estándar en SQL están en formato de una sola línea, con dos guiones:
- Este es un comentario de una sola línea - seguido de una segunda línea SELECCIONE CONTAR ( * ) DE Autores DONDE Autores . nombre = 'Smith' ; - Nota: solo queremos 'smith' - este comentario aparece después del código SQL
Alternativamente, Transact-SQL , MySQL , SQLite , PostgreSQL y Oracle admiten una sintaxis de formato de comentario idéntica al estilo de "comentario de bloque" utilizado en la sintaxis de C y Java . [52] [53] [54] [55] [56]
MySQL también admite comentarios desde el carácter hash (#) hasta el final de la línea.
Rápido
Los comentarios de una sola línea comienzan con dos barras diagonales (//):
// Este es un comentario.
Los comentarios de varias líneas comienzan con una barra inclinada seguida de un asterisco (/ *) y terminan con un asterisco seguido de una barra inclinada (* /):
/ * Esto también es un comentario pero está escrito en varias líneas. * /
Los comentarios de varias líneas en Swift se pueden anidar dentro de otros comentarios de varias líneas. Usted escribe comentarios anidados iniciando un bloque de comentarios de varias líneas y luego iniciando un segundo comentario de varias líneas dentro del primer bloque. A continuación, se cierra el segundo bloque, seguido del primer bloque:
/ * Este es el comienzo del primer comentario de varias líneas. / * Este es el segundo comentario de varias líneas anidado. * / Este es el final del primer comentario de varias líneas. * /
XML
Los comentarios en XML (o HTML) se introducen con
y puede extenderse en varias líneas hasta que el terminador,
->
Por ejemplo,
name = "context" value = "public" />
Temas de seguridad
En los idiomas interpretados, los comentarios son visibles para el usuario final del programa. En algunos casos, como las secciones de código que están "comentadas", esto puede presentar una vulnerabilidad de seguridad . [57]
Ver también
- Docstring , un tipo específico de comentario que se analiza y se retiene durante el tiempo de ejecución del programa.
- Shebang , el uso de #! como una directiva de intérprete en scripts en sistemas similares a Unix
- Etiqueta de comentario HTML
- Programación alfabetizada , paradigma de documentación alternativo
- Sintaxis de comentarios en varios lenguajes de programación.
notas y referencias
- ^ El código fuente se puede dividir en código de programa (que consta de instrucciones traducibles por máquina); y comentarios (que incluyen notas legibles por humanos y otros tipos de anotaciones en apoyo del código del programa). Penny Grubb, Armstrong Takang (2003). Mantenimiento de software: conceptos y práctica . World Scientific. págs. 7, plese start120-121. ISBN 978-981-238-426-3.
- ^ Para los propósitos de este artículo, los comentarios del lenguaje de programación se tratan como indistinguibles de los comentarios que aparecen en lenguajes de marcado , archivos de configuración y otros contextos similares. Además, el lenguaje de marcas a menudo está estrechamente integrado con el código del lenguaje de programación, especialmente en el contexto de la generación de código . Ver, por ejemplo, Ganguli, Madhushree (2002). Haciendo uso de Jsp . Nueva York: Wiley. ISBN 978-0-471-21974-3., Hewitt, Eben (2003). Java para desarrolladores de Coldfusion . Upper Saddle River: Educación de Pearson. ISBN 978-0-13-046180-3.
- ^ Dixit, JB (2003). Fundamentos y programación en C . Publicaciones Laxmi. ISBN 978-81-7008-882-0.
- ^ Higham, Desmond (2005). Guía de MATLAB . SIAM. ISBN 978-0-89871-578-1.
- ^ Vermeulen, Al (2000). Los elementos del estilo Java . Prensa de la Universidad de Cambridge. ISBN 978-0-521-77768-1.
- ^ a b c "Usando el comentario correcto en Java" . 2000-03-04 . Consultado el 24 de julio de 2007 .
- ^ WR, Dietrich (2003). Reconocimiento de patrones aplicados: algoritmos e implementación en C ++ . Saltador. ISBN 978-3-528-35558-6.ofrece puntos de vista sobre el uso adecuado de los comentarios en el código fuente. pag. 66.
- ^ a b Keyes, Jessica (2003). Manual de ingeniería de software . Prensa CRC. ISBN 978-0-8493-1479-7.analiza los comentarios y la "ciencia de la documentación" p. 256.
- ^ a b c Los elementos del estilo de programación , Kernighan y Plauger
- ^ a b Código completo , McConnell
- ^ Spinellis, Diomidis (2003). Lectura de código: la perspectiva del código abierto . Addison-Wesley. ISBN 978-0-201-79940-8.
- ^ "CodePlotter 1.6 - Agregue y edite diagramas en su código con esta herramienta 'similar a Visio'" . Archivado desde el original el 14 de julio de 2007 . Consultado el 24 de julio de 2007 .
- ^ a b Niederst, Jennifer (2006). Diseño web en pocas palabras: una referencia rápida de escritorio . O'Reilly. ISBN 978-0-596-00987-8.A veces, la diferencia entre un "comentario" y otros elementos sintácticos de un lenguaje de programación o de marcado conlleva matices sutiles. Niederst indica una de esas situaciones al afirmar: "Desafortunadamente, el software XML considera los comentarios como información sin importancia y puede simplemente eliminar los comentarios de un documento antes de procesarlo. Para evitar este problema, utilice una sección XML CDATA en su lugar".
- ^ Ver, por ejemplo, Wynne-Powell, Rod (2008). Mac Os X para fotógrafos: flujo de trabajo de imágenes optimizado para el usuario de Mac . Oxford: Focal Press. ISBN 978-0-240-52027-8. página 243
- ^ Cordero, Linda (1998). Aprendiendo el editor de VI . Sebastopol: O'Reilly & Associates. ISBN 978-1-56592-426-0. describe el uso de la sintaxis modeline en los archivos de configuración de Vim.
- ^ Ver, por ejemplo, Berlín, Daniel (2006). Practical Subversion, segunda edición . Berkeley: APulse. ISBN 978-1-59059-753-8. página 168.
- ^ Ambler, Scott (2004). The Object Primer: desarrollo basado en modelos ágiles con UML 2.0 . Prensa de la Universidad de Cambridge. ISBN 978-1-397-80521-8.
- ^ Definición de función con docstring en Clojure
- ^ Murach. C # 2005 . pag. 56.
- ^ c2: Comentarios calientes
- ^ "codificación de clase" . Ruby . ruby-lang.org . Consultado el 5 de diciembre de 2018 .
- ^ "PEP 263 - Definición de codificaciones de código fuente Python" . Python.org . Consultado el 5 de diciembre de 2018 .
- ^ Polacek, Marek (10 de marzo de 2017). "-Wimplicit-fallthrough en GCC 7" . Desarrollador de Red Hat . Red Hat . Consultado el 10 de febrero de 2019 .
- ^ "Los programadores de Microsoft escondieron un montón de blasfemias en el código de software temprano" , Lisa Eadicicco, 27 de marzo de 2014, businessinsider.com.au
- ^ (ver, por ejemplo, Linux Swear Count ).
- ^ Goodliffe, Pete (2006). Code Craft . San Francisco: No Starch Press. ISBN 978-1-59327-119-0.
- ^ Smith, T. (1991). Principios y técnicas de programación intermedia con Pascal . Belmont: Pub del oeste. Co. ISBN 978-0-314-66314-6.
- ^ Ver, por ejemplo, Koletzke, Peter (2000). Formularios e informes avanzados para desarrolladores de Oracle . Berkeley: Osborne / McGraw-Hill. ISBN 978-0-07-212048-6. página 65.
- ^ "Peor práctica: malos comentarios" . Consultado el 24 de julio de 2007 .
- ^ Morelli, Ralph (2006). Java, Java, Java: resolución de problemas orientada a objetos . Prentice Hall College. ISBN 978-0-13-147434-5.
- ^ a b "Cómo escribir comentarios de documentos para la herramienta Javadoc" . Consultado el 24 de julio de 2007 .Las pautas de Javadoc especifican que los comentarios son cruciales para la plataforma. Además, el nivel de detalle apropiado está bastante bien definido: "Dedicamos tiempo y esfuerzo a especificar las condiciones de los límites, los rangos de argumentos y los casos de esquina en lugar de definir términos de programación comunes, redactar descripciones conceptuales e incluir ejemplos para desarrolladores".
- ^ Yourdon, Edward (2007). Técnicas de estructura y diseño de programas . Universidad de Michigan. 013901702X.Los comentarios inexistentes pueden dificultar la comprensión del código, pero los comentarios pueden ser perjudiciales si son obsoletos, redundantes, incorrectos o dificultan la comprensión del propósito previsto del código fuente.
- ^ Dewhurst, Stephen C (2002). Problemas de C ++: evitar problemas comunes en la codificación y el diseño . Addison-Wesley Professional. ISBN 978-0-321-12518-7.
- ^ "Estilo de codificación" . Archivado desde el original el 8 de agosto de 2007 . Consultado el 24 de julio de 2007 .
- ^ "Allen Holub" . Archivado desde el original el 20 de julio de 2007 . Consultado el 24 de julio de 2007 .
- ^ Allen Holub, Suficiente cuerda para dispararse en el pie , ISBN 0-07-029689-8 , 1995, McGraw-Hill
- ^ Ken Thompson. "Referencia de los usuarios a B" . Consultado el 21 de julio de 2017 .
- ^ "PEP 0350 - Etiquetas de código" , Python Software Foundation
- ^ "Nunca olvides nada antes, después y durante la codificación" , usando comentarios de "etiqueta de código" como residuos productivos
- ^ "Uso de la lista de tareas" , msdn.microsoft.com
- ^ "Deja un comentario en running-config" . Cisco Learning Network (foro de discusión) .
- ^ "Guía de configuración de administración de archivos de configuración, Cisco IOS XE Release 3S (ASR 900 Series)" .
- ^ "Programación alfabetizada" . haskell.org .
- ^ "Programación en Lua 1.3" . www.Lua.org . Consultado el 8 de noviembre de 2017 .
- ^ macros.extractDocCommentsAndRunnables
- ^ "Comentarios" . www.freepascal.org . Consultado el 20 de septiembre de 2017 .
- ^ "perlpod - el formato simple de documentación antigua" . Consultado el 12 de septiembre de 2011 .
- ^ "Pod :: ParseUtils - ayudantes para el análisis y la conversión de POD" . Consultado el 12 de septiembre de 2011 .
- ^ a b "Documentación de Perl 6 - Sintaxis (comentarios)" . Consultado el 6 de abril de 2017 .
- ^ a b "Sintaxis básica de Python 3" . Consultado el 25 de febrero de 2019 .
Las comillas triples se tratan como cadenas regulares con la excepción de que pueden abarcar varias líneas. Por cadenas regulares me refiero a que si no están asignadas a una variable, serán recolectadas inmediatamente como basura tan pronto como se ejecute ese código. por lo tanto, el intérprete no los ignora de la misma manera que #a comentario.
- ^ "Consejo de Python: puede utilizar cadenas de varias líneas como comentarios de varias líneas" , 11 de septiembre de 2011, Guido van Rossum
- ^ Talmage, Ronald R. (1999). Microsoft SQL Server 7 . Prima Publishing. ISBN 978-0-7615-1389-6.
- ^ "Manual de referencia de MySQL 8.0" . Oracle Corporation . Consultado el 2 de enero de 2020 .
- ^ "SQL entendido por SQLite" . Consorcio SQLite . Consultado el 2 de enero de 2020 .
- ^ "Documentación de PostgreSQL 10.11" . El Grupo de Desarrollo Global de PostgreSQL . Consultado el 2 de enero de 2020 .
- ^ "Referencia SQL de la base de datos Oracle®" . Oracle Corporation . Consultado el 2 de enero de 2020 .
- ^ Andress, Mandy (2003). Sobrevivir a la seguridad: cómo integrar personas, procesos y tecnología . Prensa CRC. ISBN 978-0-8493-2042-2.
Otras lecturas
- Movshovitz-Attias, Dana y Cohen, William W. (2013) Modelos de lenguaje natural para predecir comentarios de programación . En Association for Computational Linguistics (ACL), 2013.
enlaces externos
- Cómo escribir comentarios por Denis Krukovsky
- Documentación del código fuente como manual de usuario en vivo de PTLogica
- Cómo escribir comentarios para la herramienta Javadoc
- Doxygen , un sistema de documentación para C, C ++, Java, Objective-C, Python, IDL y, hasta cierto punto, PHP, C # y D