stringtranslate.com

Comentario (programación informática)

Ilustración del código fuente de Java con comentarios de prólogo indicados en rojo y comentarios en línea en verde . El código del programa está en azul .

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 .

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

Usos

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]

Planificación y 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í.

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

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 debería reescribirse, o de que la denominación no es correcta.

"No documentes el código incorrecto: reescríbalo". [9]
"Los buenos comentarios no repiten el código ni lo explican, sino que aclaran su propósito. Los comentarios deberían explicar, a un nivel de abstracción más alto que el código, lo que estás intentando 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 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" )  

Descripción algorítmica

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 );               

Inclusión de recursos

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]

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

Depuración

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.

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]

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]

Extensión de sintaxis

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.

Usos de la directiva

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:

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

Alivio del estrés

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]

Puntos de vista normativos

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]

Necesidad de comentarios

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 .

Nivel de detalle

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]

Estilos

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]

Bloquear comentario

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]

Comentarios de línea

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.

Etiquetas

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:

Ejemplos

Comparación

Las convenciones tipográficas para especificar comentarios varían ampliamente. Además, los lenguajes de programación individuales a veces ofrecen variantes únicas.

Ada

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

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    

Script de Apple

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" )

BÁSICO

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    

do

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 .

Configuración de Cisco IOS y IOS-XE

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

Fusión fría

ColdFusion 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

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

Fortran IV

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.

Fortran 90

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 * ! * * ...    

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 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 {}              

Java

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

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

Lua

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 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, 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 .

MATLAB

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

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

OCaml utiliza comentarios anidables, lo que resulta útil al comentar un bloque de código.

codeLine (*nivel de comentario 1(*nivel de comentario 2*)*)

Pascal, Delfos

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 (**).

Perl

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

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

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 ) { ...}

PHP

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.  */}

Potencia Shell

Comentarios en Windows PowerShell

# Comentario de una sola línea Write-Host  "¡Hola, mundo!"<# Comentario de varias  líneas  #>Write-Host  "¡Adiós, mundo!"

Pitón

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 sintaxis

Los 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""" 

Rubí

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" 

SQL

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.

Rápido

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

XML (o HTML)

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.

Problemas de seguridad

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]

Véase también

Notas y referencias

  1. ^ El código fuente se puede dividir en código de programa (que consiste en instrucciones traducibles por máquina) y comentarios (que incluyen notas legibles por humanos y otros tipos de anotaciones en apoyo del código de programa). Penny Grubb, Armstrong Takang (2003). Mantenimiento de software: conceptos y práctica . World Scientific. pp. 7, comience por 120-121. ISBN 978-981-238-426-3.
  2. ^ Para los fines de este artículo, los comentarios de lenguajes de programación se tratan como indistintos de los comentarios que aparecen en lenguajes de marcado , archivos de configuración y otros contextos similares. Además, el lenguaje de marcado 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 . Véase, por ejemplo, Ganguli, Madhushree (2002). Making Use of Jsp . Nueva York: Wiley. ISBN 978-0-471-21974-3.Hewitt , Eben (2003). Java para desarrolladores de Coldfusion . Upper Saddle River: Pearson Education. ISBN 978-0-13-046180-3.
  3. ^ Dixit, JB (2003). Fundamentos de computación y programación en C. Laxmi Publications. ISBN 978-81-7008-882-0.
  4. ^ Higham, Desmond (2005). Guía de MATLAB . SIAM. ISBN 978-0-89871-578-1.
  5. ^ Vermeulen, Al (2000). Los elementos del estilo Java. Cambridge University Press. ISBN 978-0-521-77768-1.
  6. ^ abc "Uso del comentario correcto en Java". 2000-03-04 . Consultado el 2007-07-24 .
  7. ^ WR, Dietrich (2003). Reconocimiento de patrones aplicado: algoritmos e implementación en C++ . Springer. ISBN 978-3-528-35558-6.Ofrece puntos de vista sobre el uso adecuado de los comentarios en el código fuente. p. 66.
  8. ^ ab Keyes, Jessica (2003). Manual de ingeniería de software . CRC Press. ISBN 978-0-8493-1479-7.analiza los comentarios y la "Ciencia de la Documentación" p. 256.
  9. ^ abc Los elementos del estilo de programación , Kernighan y Plauger
  10. ^ ab Código completo , McConnell
  11. ^ Spinellis, Diomidis (2003). Lectura de código: la perspectiva del código abierto . Addison-Wesley. ISBN 978-0-201-79940-8.
  12. ^ "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 .
  13. ^ ab Niederst, Jennifer (2006). Diseño web en pocas palabras: una referencia rápida para computadoras de escritorio . O'Reilly. ISBN 978-0-596-00987-8.A veces, la diferencia entre un "comentario" y otros elementos de sintaxis de un lenguaje de programación o de marcado implica 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 eliminarlos de un documento antes de procesarlo. Para evitar este problema, utilice una sección CDATA de XML en su lugar".
  14. ^ Véase, 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. pág. 243. ISBN. 978-0-240-52027-8.
  15. ^ Lamb, Linda (1998). Aprendiendo a usar el editor VI. Sebastopol: O'Reilly & Associates. ISBN 978-1-56592-426-0.describe el uso de la sintaxis de modeline en los archivos de configuración de Vim.
  16. ^ Véase, por ejemplo, Berlin, Daniel (2006). Practical Subversion, segunda edición . Berkeley: APress. pág. 168. ISBN. 978-1-59059-753-8.
  17. ^ Ambler, Scott (2004). Introducción a los objetos: desarrollo ágil basado en modelos con UML 2.0 . Cambridge University Press. ISBN 978-1-397-80521-8.
  18. ^ Definición de función con docstring en Clojure
  19. ^ Murach. C# 2005 . pág. 56.
  20. ^ c2: Comentarios destacados
  21. ^ "Codificación de clase". Ruby . ruby-lang.org . Consultado el 5 de diciembre de 2018 .
  22. ^ "PEP 263 – Definición de codificaciones de código fuente de Python". Python.org . Consultado el 5 de diciembre de 2018 .
  23. ^ Polacek, Marek (10 de marzo de 2017). "-Wimplicit-fallthrough in GCC 7". Red Hat Developer . Red Hat . Consultado el 10 de febrero de 2019 .
  24. ^ Lisa Eadicicco (27 de marzo de 2014). "Los programadores de Microsoft ocultaron un montón de blasfemias en el código de software inicial". Business Insider Australia . Archivado desde el original el 29 de diciembre de 2016.
  25. ^ (ver por ejemplo, Linux Swear Count).
  26. ^ Goodliffe, Pete (2006). Código artesanal . San Francisco: No Starch Press. ISBN 978-1-59327-119-0.
  27. ^ Smith, T. (1991). Principios y técnicas de programación intermedia con Pascal . Belmont: West Pub. Co. ISBN 978-0-314-66314-6.
  28. ^ Véase, por ejemplo, Koletzke, Peter (2000). Oracle Developer Advanced Forms & Reports . Berkeley: Osborne/McGraw-Hill. ISBN. 978-0-07-212048-6.Página 65.
  29. ^ "Peores prácticas: malos comentarios" . Consultado el 24 de julio de 2007 .
  30. ^ Morelli, Ralph (2006). Java, Java, Java: resolución de problemas orientada a objetos . Prentice Hall College. ISBN 978-0-13-147434-5.
  31. ^ ab "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 adecuado está bastante bien definido: "Dedicamos tiempo y esfuerzo a especificar condiciones límite, rangos de argumentos y casos extremos en lugar de definir términos de programación comunes, escribir descripciones generales conceptuales e incluir ejemplos para desarrolladores".
  32. ^ Yourdon, Edward (2007). Técnicas de diseño y estructura 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 si de alguna otra manera dificultan la comprensión del propósito previsto para el código fuente.
  33. ^ Dewhurst, Stephen C (2002). Errores en C++: cómo evitar problemas comunes en la codificación y el diseño . Addison-Wesley Professional. ISBN 978-0-321-12518-7.
  34. ^ "Estilo de codificación". Archivado desde el original el 8 de agosto de 2007. Consultado el 24 de julio de 2007 .
  35. ^ "Allen Holub". Archivado desde el original el 20 de julio de 2007. Consultado el 24 de julio de 2007 .
  36. ^ Allen Holub, Cuerda suficiente para pegarse un tiro en el pie , ISBN 0-07-029689-8 , 1995, McGraw-Hill 
  37. ^ Ken Thompson. "Referencia de los usuarios a B" . Consultado el 21 de julio de 2017 .
  38. ^ "PEP 0350 – Etiquetas de código", Python Software Foundation
  39. ^ "Nunca olvides nada antes, después y mientras codificas", uso de comentarios de "etiqueta de código" como recordatorios productivos
  40. ^ "Uso de la lista de tareas", msdn.microsoft.com
  41. ^ "Deje un comentario en running-config". Cisco Learning Network (foro de discusión) .
  42. ^ "Guía de configuración de administración de archivos de configuración, Cisco IOS XE versión 3S (serie ASR 900)".
  43. ^ "Programación alfabetizada". haskell.org .
  44. ^ "Programación en Lua 1.3". www.Lua.org . Consultado el 8 de noviembre de 2017 .
  45. ^ macros.extractDocCommentsAndRunnables
  46. ^ Kathleen Jensen, Niklaus Wirth (1985). Manual e informe del usuario de Pascal . Springer-Verlag. ISBN 0-387-96048-1.
  47. ^ NiklausWirth (1983). Programación en Modula-2 . Springer-Verlag. ISBN 0-387-15078-1.
  48. ^ * Martin Reiser, Niklaus Wirth (1992). Programación en Oberon . Addison-Wesley. ISBN 0-201-56543-9.
  49. ^ "perlpod – el formato de documentación tradicional" . Consultado el 12 de septiembre de 2011 .
  50. ^ "Pod::ParseUtils: ayudas para el análisis y la conversión de POD" . Consultado el 12 de septiembre de 2011 .
  51. ^ ab "Documentación de Perl 6 – Sintaxis (comentarios)" . Consultado el 6 de abril de 2017 .
  52. ^ ab "Sintaxis básica de Python 3". Archivado del original el 19 de agosto de 2021 . Consultado el 25 de febrero de 2019 . 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.
  53. ^ "Consejo de Python: puedes usar cadenas de varias líneas como comentarios de varias líneas", 11 de septiembre de 2011, Guido van Rossum
  54. ^ Talmage, Ronald R. (1999). Microsoft SQL Server 7. Prima Publishing. ISBN 978-0-7615-1389-6.
  55. ^ "Manual de referencia de MySQL 8.0". Oracle Corporation . Consultado el 2 de enero de 2020 .
  56. ^ "SQL tal como lo entiende SQLite". Consorcio SQLite . Consultado el 2 de enero de 2020 .
  57. ^ "Documentación de PostgreSQL 10.11". The PostgreSQL Global Development Group . Consultado el 2 de enero de 2020 .
  58. ^ "Oracle® Database SQL Reference". Oracle Corporation . Consultado el 2 de enero de 2020 .
  59. ^ Andress, Mandy (2003). Cómo sobrevivir a la seguridad: cómo integrar personas, procesos y tecnología . CRC Press. ISBN 978-0-8493-2042-2.

Lectura adicional

Enlaces externos