Comentario (programación informática)

Los comentarios pueden explicar la intención del autor : por qué el código es como es. Algunos sostienen que describir qué hace el código es superfluo. La necesidad de explicar el qué es señal de que es demasiado complejo y debería revisarse.

"No documentes el código malo, reescríbelo." ^{[ 9 ]}

"Los buenos comentarios no repiten el código ni lo explican. Aclaran su intención. Los comentarios deben explicar, a un nivel de abstracción superior al del código, lo que se intenta hacer." ^{[ 10 ]}

Los comentarios pueden explicar por qué se optó por escribir código que contradice las convenciones o las mejores prácticas. Por ejemplo:

' La segunda variable se reduce debido a errores del servidor que se producen al reutilizar datos del formulario. ' No hay documentación disponible sobre el problema de comportamiento del servidor, así que simplemente se está programando una solución alternativa. vtx = servidor.mappath ( " configuración local" )

El siguiente ejemplo explica por qué se eligió un algoritmo de ordenación por inserción en lugar de un algoritmo de ordenación rápida , ya que, en teoría, el primero es más lento que el segundo.

lista = [ f ( b ), f ( b ), f ( c ), f ( d ), f ( a ), ... ] ; // Se necesita una ordenación estable. Además, el rendimiento realmente no importa. ordenación_inserción ( lista );

Los comentarios pueden describir un algoritmo como pseudocódigo . Esto podría hacerse antes de escribir el código, como un primer borrador. Si se dejan en el código, pueden simplificar la revisión del mismo, ya que permiten comparar el código resultante con la lógica prevista. Por ejemplo:

/* Recorre en orden inverso todos los elementos devueltos por el servidor (deben procesarse cronológicamente) */ for ( i = ( numElementsReturned - 0 ); i >= 1 ; i -- ) { /* Procesa los datos de cada elemento */ updatePattern ( i , returnedElements [ i ]); }

En ocasiones, el código contiene una solución novedosa o destacable que justifica un comentario explicativo. Dichas explicaciones pueden ser extensas e incluir diagramas y demostraciones matemáticas formales. Esto puede describir lo que hace el código en lugar de su intención, pero puede ser útil para su mantenimiento. Esto podría aplicarse a dominios de problemas altamente especializados o a optimizaciones, construcciones o llamadas a funciones poco utilizadas. ^{[ 11 ]}

Cuando algún aspecto del código se basa en información de una referencia externa, los comentarios enlazan a dicha referencia. Por ejemplo, mediante una URL o el nombre del libro y el número de página.

Una práctica común entre los desarrolladores es comentar una o más líneas de código. El programador añade una sintaxis de comentarios que convierte el código del programa en comentarios, de modo que lo que era código ejecutable ya no se ejecute en tiempo de ejecución. A veces, esta técnica se utiliza para encontrar la causa de un error. Al comentar y ejecutar sistemáticamente partes del programa, se puede localizar el código fuente problemático. ^{[ 12 ]}

Muchos entornos de desarrollo integrados (IDE) permiten agregar y eliminar comentarios mediante acciones de interfaz de usuario prácticas , como un atajo de teclado .

Los comentarios pueden almacenar metadatos sobre el código. Los metadatos comunes incluyen el nombre del autor original y de los responsables del mantenimiento, las fechas de la primera redacción y modificación, el enlace a la documentación de desarrollo y de usuario, e información legal como los derechos de autor y la licencia del software . En raras ocasiones, se pueden incluir datos binarios codificados en texto .

Algunas herramientas de programación escriben metadatos en el código como comentarios. ^{[ 13 ]} Por ejemplo, una herramienta de control de versiones podría escribir metadatos como autor, fecha y número de versión en cada archivo cuando se confirma en el repositorio. ^{[ 14 ]}

En ocasiones, la información almacenada en los comentarios es utilizada por herramientas de desarrollo distintas del traductor , que es la herramienta principal que procesa el código. Esta información puede incluir metadatos (que suelen utilizar los generadores de documentación) o la configuración de la herramienta.

Algunos editores de código fuente admiten la configuración mediante metadatos en comentarios. ^{[ 15 ]} Un ejemplo particular es la función modeline de Vim , que configura el manejo del carácter de tabulación. Por ejemplo:

# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4

Un generador de documentación de API analiza la información de un código fuente para generar la documentación de la API. Muchos permiten leer información de los comentarios, a menudo analizando metadatos, para controlar el contenido y el formato del documento resultante.

Aunque algunos afirman que la documentación de API puede ser de mayor calidad cuando se escribe de forma más tradicional y manual, otros afirman que almacenar la información de la documentación en comentarios de código simplifica el proceso de documentación, además de aumentar la probabilidad de que la documentación se mantenga actualizada. ^{[ 16 ]} Algunos ejemplos incluyen Javadoc , Ddoc, Doxygen , Visual Expert y PHPDoc . Python , Lisp , Elixir y Clojure admiten formas de docstring . ^{[ 17 ]} C# , F# y Visual Basic .NET implementan una característica similar llamada "Comentarios XML" que IntelliSense lee del ensamblado .NET compilado . ^{[ 18 ]}

Se puede incluir una visualización de arte ASCII, como un logotipo , un diagrama o un diagrama de flujo, en un comentario. ^{[ 19 ]}

El siguiente fragmento de código muestra el flujo de proceso de un script de administración del sistema ( archivo de script de Windows ). Aunque una sección que marca el código aparece como un comentario, el diagrama se encuentra en una sección XML CDATA , que técnicamente no es un comentario, pero cumple la misma función aquí. ^{[ 20 ]} Si bien este diagrama podría estar en un comentario, el ejemplo ilustra un caso en el que el programador optó por no usar un comentario para incluir recursos en el código fuente. ^{[ 20 ]}

<!-- inicio: wsf_resource_nodes --> <resource id= "ProcessDiagram000" > <![CDATA[ HostApp (Main_process)  |  V script.wsf (app_cmd) --> ClientApp (async_run, batch_process)  |  |  V  mru.ini (mru_history) ]]> </resource>

En ocasiones, los comentarios describen procesos de desarrollo relacionados con el código. Por ejemplo, pueden describir cómo compilar el código o cómo enviar cambios al responsable del mantenimiento del software .

En ocasiones, el código formateado como comentario se sobrecarga para transmitir información adicional al traductor, como comentarios condicionales. Por lo tanto, la sintaxis que generalmente indica un comentario puede representar en realidad código de programa, no código de comentario. Esta sintaxis puede ser una forma práctica de mantener la compatibilidad al tiempo que se añade funcionalidad adicional, pero algunos consideran esta solución una chapuza . ^{[ 21 ]}

Otros ejemplos incluyen directivas del intérprete :

• El " shebang " de Unix #!se utiliza en la primera línea de un script para indicar el intérprete que se va a utilizar.
• "Comentarios mágicos" que identifican la codificación que utiliza un archivo fuente, ^{[ 22 ]} por ejemplo, la PEP 263 de Python. ^{[ 23 ]}

El siguiente script para un sistema tipo Unix muestra ambos usos:

#!/usr/bin/env python3 # -*- coding: UTF-8 -*- print ( "Probando" )

El compilador gcc (desde 2017) busca un comentario en una instrucción switch si un caso pasa al siguiente. Si no encuentra una indicación explícita de que se ejecuta el siguiente caso, el compilador emite una advertencia sobre un posible problema de codificación. Insertar dicho comentario sobre la ejecución del siguiente caso es una convención de larga data, y el compilador ha codificado esta práctica. ^{[ 24 ]} Por ejemplo:

interruptor ( comando ) {caso CMD_SHOW_HELP_AND_EXIT :mostrar_ayuda ();/* Fallo continuo */caso CMD_EXIT :salir ();romper ;}

Para aliviar el estrés o intentar hacer reír, a veces los programadores añaden comentarios sobre la calidad del código, las herramientas, la competencia, los empleadores, las condiciones de trabajo u otros temas que podrían considerarse poco profesionales , a veces utilizando palabrotas . ^{[ 25 ] [ 26 ]}

Los expertos tienen opiniones diversas sobre si los comentarios son apropiados en el código fuente y cuándo lo son. ^{[ 9 ] [ 30 ]} Algunos afirman que el código fuente debe escribirse con pocos comentarios, basándose en que debe ser autoexplicativo o autodocumentado . ^{[ 9 ]} Otros sugieren que el código debe estar 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). ^{[ 31 ] [ 32 ]}

Entre estas posturas se encuentra la afirmación de que los comentarios no son ni beneficiosos ni perjudiciales en 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 de alguna otra manera inútiles. ^{[ 33 ] [ 34 ]}

En el enfoque de diseño por contrato para la programación, a veces se utilizan comentarios para documentar los contratos .

Dependiendo del público al que va dirigido el código y de otras consideraciones, el nivel de detalle y descripción puede variar considerablemente.

Por ejemplo, el siguiente comentario en Java sería adecuado en un texto introductorio diseñado para enseñar programación básica:

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. Tales descripciones rudimentarias son inconsistentes con la directriz: "Los buenos comentarios... aclaran la intención". ^{[ 10 ]} Además, para 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. ^{[ 32 ]}

Muchos lenguajes que utilizan llaves, como C, C++ y sus numerosos derivados, delimitan un comentario de línea con //y un comentario de bloque con /*y */. Originalmente, C carecía de comentarios de línea, pero se añadieron en C99 . Algunos lenguajes destacados son: C, C++, C# , D , Java , JavaScript y Swift . Por ejemplo:

/* * Comprueba si se ha superado el límite máximo de procesos, pero asegúrate de excluir a root. * Esto es necesario para que el inicio de sesión pueda establecer un límite de procesos por usuario * inferior al de los procesos que ejecuta root. */ bool isOverMaximumProcessLimit () { // TODO implementar }

Algunos lenguajes, incluidos D ^{[ 41 ]} y Swift ^{[ 42 ]} , permiten anidar comentarios de bloque, mientras que otros no, incluidos C y C++.

Un ejemplo de bloques anidados en D:

// comentario de línea /*  comentario de bloque */ /+ inicio del bloque exterior  /+ bloque interior +/  fin del bloque exterior +/

Un ejemplo de bloques anidados en Swift:

/* Este es el inicio del comentario externo.  /* Este es el comentario anidado. */ Este es el final del comentario externo. */

Un patrón común en muchos lenguajes de scripting es delimitar un comentario de línea con #. La compatibilidad con comentarios de bloque varía. Algunos lenguajes destacados son : Bash , Raku , Ruby , Perl , PowerShell , Python y R.

Un ejemplo en R:

# Este es un comentario print ( "Esto no es un comentario" ) # Este es otro comentario

puts "no es un comentario" # esto es un comentario puts "no es un comentario" =begin lo que va en estas líneas es solo para el lector humano =end puts "no es un comentario"

=item Pod::List-E<gt>new() 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 }); =cut sub new { ... }

#`{{ "comentando" esta versión toggle-case(Str:D $s) Cambia el formato 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 paréntesis se usa ahora ) { ... } 

# Comentario de una sola línea <# Comentario de varias  líneas  #>

""" En la parte superior de un archivo, esta es la cadena de documentación del módulo """clase MyClass : """Documentación de la clase"""def my_method ( self ): """Documentación del método"""

En general, los lenguajes de marcado varían en su sintaxis de comentarios, pero algunos de los formatos de marcado de Internet más importantes, como HTML y XML, delimitan un comentario de bloque con <!--y y no ofrecen soporte para comentarios de línea. Un ejemplo en XML:-->

<!-- seleccione el contexto aquí --> <param name= "context" value= "public" />

Para garantizar la compatibilidad con SGML , no se permite el uso de doble guion (--) dentro de los comentarios.

ColdFusion proporciona una sintaxis similar a la de los comentarios HTML , pero utiliza tres guiones en lugar de dos. CodeFusion permite comentarios de bloque anidados.

{- este es un comentario en más líneas -} -- y este es un comentario en una línea putStrLn "Wikipedia" -- este es otro comentario

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 hay que dejar una línea en blanco después del código. 

\usepackage { verbatim } \newenvironment { code }{ \verbatim }{ \endverbatim }

% 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í más explicación usando el marcado \LaTeX {}

--[[Un comentario de varias líneas ]]

Un conjunto relativamente flexible de lenguajes utilizados --para comentarios de una sola línea. Algunos lenguajes destacados son: Ada , Eiffel , Haskell , Lua , SQL y VHDL . La compatibilidad con comentarios en bloque varía. Un ejemplo en Ada:

-- la tarea del controlador de tráfico aéreo toma solicitudes de despegue y aterrizaje tipo de tarea Controller ( My_Runway : Runway_Access ) es -- entradas de tarea para paso de mensajes síncrono entrada Request_Takeoff ( ID : in Airplane_ID ; Takeoff : out Runway_Access ); entrada Request_Approach ( ID : in Airplane_ID ; Approach : out Runway_Access ); fin Controller ;