En la programación de computadoras, un comentario es una construcción del lenguaje de programación destinada a

incrustar anotaciones legibles al programador en el código fuente de un Programa informático.

¿Qué es un COMENTARIO en programación?

Un comentario en programación es la línea de texto en nuestro código fuente que el

compilador ignora.

Sabemos que nuestro código fuente está compuesto de instrucciones, y el compilador traduce
esas instrucciones del lenguaje de programación que estamos usando a lenguaje máquina.

Cuando el compilador se encuentra con un comentario, esa línea, o varias de ellas, no las traduce,
y continúa buscando en la instrucción siguiente.

Los comentarios en programación se utilizan para poner aclaraciones del código, y así es más
fácil de entender lo que hace, aunque también se utilizan para anular parte de un código.

Aunque con un sistema de control de versiones como GIT no sería necesario hacer eso.

En algunos lenguajes, como Java, se utilizan los comentarios con un formato específico para
crear documentación aparte (llamado JavaDoc).

Índice del contenido [ocultar]

  1 Ejemplos de comentarios
o 1.1 Comentario en Visual Basic
o 1.2 Comentario en Pascal
o 1.3 Comentario en Python
o 1.4 Comentario en HTML

Ejemplos de comentarios

La mayoría de lenguajes de programación usan la sintaxis del comentario en C, que es la

siguiente:

/* Esto es un comentario */

Con la sintaxis /* */, podemos escribir en varias líneas

/* Esto
es
un
comentario */

En algunos lenguajes como en Java puedes usar los comentarios para crear documentación para
tus clases, o una variable o un método.

De esta manera, usaríamos javadoc para generar ficheros de ayuda en HTML y servirían para
describir el elemento declarado:

/** Comentario de documentación

* puede
* tener
* varias líneas
*/

C++ también añadió la opción de hacer un comentario en una línea:

//Comentario de tipo C++

Aunque recordemos que Java, C++, C, PHP y muchos lenguajes aceptan los dos tipos de
comentario.

En otros lenguajes, los comentarios se hacen de otra forma. Veamos algunos de ellos

Comentario en Visual Basic

Todas las versiones de Visual Basic usan el símbolo '

'Comentario en
'visual basic
Comentario en Pascal

En Pascal, y también Delphi, para escribir comentario usamos (* *)

(* Comentario en Pascal *)
 Comentario en Python

En Python usamos # como símbolo para iniciar un comentario en línea.

También podemos escribir comentarios multilíneas, escribimos la comilla doble 3 veces, así:

"""Comentario multilinea.
Segunda línea del comentario """
Comentario en HTML

En HTML, podemos escribir un comentario de esta manera:

<!-- Comentario HTML -->

JAVA

Java ofrece tres tipos de comentarios: dos para comentarios regulares en el código fuente y uno para
la documentación especial del sistema javadoc.

 Comentarios de varias líneas.

Los comentarios de varias líneas se incluyen entre los símbolos /* y */, como en C y C++.

/*
Este es un ejemplo de
un comentario de varias
líneas.
*/

 Comentarios de una sola línea.

Para comentariar una sola línea se utiliza la doble diagonal //. El comentario se inicia cuando
se encuentra la doble diagonal y continua hasta el final de la línea.

// Este es un comentario de una sola linea

//Este es otro comentario

 Comentarios para documentación.

Realmente este tipo de comentario es el mismo que el de varias líneas con la diferencia de que
la información que contenga será usada para un procesamiento especial que lleva a cabo la
herramienta javadoc.

Se distingue del comentario de varias líneas porque se agrega un asterisco adicional al inicio
del comentario.

/**
Este tipo de comentarios
los utiliza la
herramienta javadoc
*/

COMENTARIOS JAVASCRIPT
JavaScript permite insertar comentarios en el código, al igual que la mayoría de los lenguajes de programación.
En concreto hay dos tipos de comentarios permitidos, los comentarios en línea que comienzan con una doble
barra: //, y los comentarios multilínea, que comienzan con /* y terminan con */.

COMENTARIOS EN JAVASCRIPT

Veamos un ejemplo. Escribe este código y guárdalo en un archivo de extensión html:

<html>
<head>
<title>Portal web - aprenderaprogramar.com</title> <meta charset="utf-8">
<script type="text/javascript">
/* Funciones JavaScript
   Versión 0.1
   Autor: César Krall
   Curso: Tutorial básico del programador web: JavaScript desde cero
*/

//Función que muestra mensaje de bienvenida

function mostrarMensaje1() {
alert('Bienvenido al curso JavaScript de aprenderaprogramar.com');
}

function mostrarMensaje2() {
//Mensaje si se hace click sobre párrafo
alert('Ha hecho click sobre el párrafo inferior');
}
</script>
</head>
<body>
<div>
<p>Aquí un párrafo de texto situado antes de la imagen, dentro de un div
contenedor</p>
<img onclick="mostrarMensaje1()" src="http://i.imgur.com/afC0L.jpg"
alt="Notepad++" title="Notepad++, un útil editor de texto">
<p style="background-color:yellow;" onclick="mostrarMensaje2()">Aquí otro
párrafo de texto. JavaScript es un lenguaje utilizado para dotar de efectos
dinámicos a las páginas web.
</p>
</div>
</body>
 </html>

Visualiza el resultado y comprueba que la página web se muestra con normalidad y que JavaScript se ejecuta
con normalidad.

Los comentarios son parte del código JavaScript. El navegador los recibe y los detecta pero los ignora al no
constituir instrucciones que hayan de ejecutarse. Sin embargo, los comentarios pueden ser visualizados si
accedemos al código fuente de la página web (cosa que puede hacer cualquier usuario). Por lo tanto en los
comentarios no debe figurar nada que pueda considerarse indebido (como “este código lo he copiado a mi
compañero de trabajo sin permiso”, ó “Para acceder a la base de datos usar como datos usuario: cesar y
contraseña: aprenderaprogramar.com”).

Los comentarios deben usarse para describir aspectos importantes. Por ejemplo, contenido de un archivo,
cometido de una función, versión, licencia, autor, copyright, aspectos que permitan una mejor comprensión del
código, avisos importantes, etc.

Obviamente los comentarios JavaScript tienen que encontrarse dentro de código JavaScript, no pueden
insertarse en cualquier parte. Por tanto deberán estar dentro de las etiquetas <script> … </script> o bien dentro
de un archivo js, no pueden encontrarse en el código HTML.

Los comentarios multilínea no se pueden anidar (es decir, no puede haber un comentario multilínea dentro de
otro comentario multilínea). Los comentarios multilínea pueden dar lugar a errores cuando se mezclan con
expresiones regulares (hablaremos de expresiones regulares más adelante).

INSERCIÓN AUTOMÁTICA DE PUNTO Y COMA

En general las sentencias JavaScript deben terminar con un punto y coma que delimita el final de una
instrucción. No obstante, en caso de que “se olvide” insertar el punto y coma delimitador, el intérprete
JavaScript lo insertará automáticamente siempre que le sea posible, facilitando que el código se ejecute.

En el código anterior, elimina los punto y coma al final se las sentencias JavaScript:

function mostrarMensaje1() {
alert('Bienvenido al curso JavaScript de
aprenderaprogramar.com')
}

function mostrarMensaje2() {
alert('Ha hecho click sobre el párrafo inferior')
}

 
Visualiza la página web en tu navegador y comprueba que JavaScript sigue funcionando. ¿Por qué? Porque el
intérprete del navegador, al encontrar que faltan los ; de cierre, los ha introducido automáticamente para
permitir que se ejecute el código. Aunque esto puede parecer una facilidad, recomendamos siempre el cierre de
toda instrucción mediante punto y coma. Esto evitará errores o que ocurran cosas indeseadas.

C#

En C# puedes escribir comentarios de una línea empezando por "//" o de varias líneas escribiendo entre "/*" y
"*/". No hace falta poner asterisco al principio de cada línea, pero Visual Studio lo hace automáticamente y
además queda mejor delimitado el comentario.

cvl-es.cs, 6 líneas      [descargar]

1. //comentario
2. int a = 1; //otro comentario
3. /* comentario
4. * de varias
5. * líneas */
6. int b = a;
7.  

Pero lo realmente interesante es la posibilidad de documentar el código directamente. Es decir, escribir

comentarios bien estructurados en XML y que éstos aparezcan como ayudas al autocompletar el nombre o
parámetros de la clase, objeto, variable, etc y además también se pueda generar la propia documentación del
programa basada exclusivamente en estos comentarios.

Todas las etiquetas son opcionales. Aquí solo se muestran unas pocas.

Documentar clases

cls-es.cs, 11 líneas      [descargar]

1. ///<summary>
2. ///Clase principal de la aplicación.
3. ///</summary>
4. ///<remarks>
5. ///Lee archivos de configuración y crea los hilos que ejecutan el
resto del programa.
6. ///</remarks>
7. class CApp {
8.     static void Main(string[] args) {
9.         ...
10.     }
11. }
12.  

Entre las etiquetas <summary> y </summary> ponemos la descripción o resumen de la clase. Las etiquetas
<remarks> y </remarks> las usamos para comentarios especiales, no se verán en el autocompletado pero sí en
la documentación.
Documentar miembros

miem-es.cs, 10 líneas      [descargar]

1. class CApp2 {
2.     ///<summary>
3.     ///Variable que almacena el número de reintentos al acceder a un
archivo.
4.     ///</summary>
5.     ///<remarks>
6.     ///Puede ser modificada en cualquier momento.
7.     ///</remarks>
8.     int var = 1;
9.     ...
10. }
11.  

El sistema es idéntico al usado para clases.

Documentar métodos/funciones

met-es.cs, 14 líneas      [descargar]

1. ///<summary>
2. ///Lee la configuración de la aplicación desde el disco.
3. ///</summary>
4. ///<return>
5. ///Devuelve true si la configuración fue leida. Si hubo algún error se
devuelve false.
6. ///</return>
7. ///<param name="archivo">
8. ///Ruta del archivo en disco a leer.
9. ///</param>
10. public bool LeeConfig(string archivo) {
11.     bool c = false;
12.     ...
13.     return c;
14. }
15.  

Entre las etiquetas <return> y </return> se explica el valor devuelto por la función, y las etiquetas <param>
se utilizan para describir cada uno de los parámetros del método/función.

Generar documentación

A parte de las ayudas al autocompletado que aparecen automaticamente en Visual Studio, SharpDevelop y
MonoDevelop al documentar el código, también se pueden generar archivos de documentación. En Windows,
usando la implementación del .NET Framework hecha por Microsoft, se utiliza el siguiente comando:

C:\>csc /doc:Documentacion.xml Programa.cs

En sistemas Unix con Mono instalado se utiliza:

mcs -doc:Documentacion.xml Programa.cs

Y en Windows con Mono instalado:

C:\>mcs /doc:Documentacion.xml Programa.cs

Documentando automáticamente

Existe un Add-in para MS Visual Studio 2003 y 2005, GhostDoc, que permite con una simple combinación de
teclas generar los comentarios de documentación basados en lo que se esté intentando comentar (una clase,
método, variable...).

Comentarios En Kotlin
En este tutorial te mostraremos las formas de escribir comentarios en Kotlin para agregar
información a tu código que te permita expresar aspectos relacionados con documentación,
intenciones, claridad, consecuencias, legalidad, etc.

 Comentarios De Una Sola Línea

 Comentarios Multilínea
 Atajos Para Comentar En IntelliJ IDEA
 Comentarios TODO
 Documentación Con KDoc

Comentarios De Una Sola Línea

Al igual que en Java y muchos otros lenguajes, el compilador de Kotlin interpreta comentarios de
una sola línea y de múltiples líneas con un formato que inicia por barra (/).

Para realizar un comentario de una sola línea, usa barra doble (//...) y seguidamente escribes
las palabras que proporcionen el contexto en el lugar del código:

fun main() {
// Ejemplo de suma de dos números
val sumOfTwoNumbers: Int // (1)

val firstNumber = 1 // (2)

val secondNumber = 5 // (3)

sumOfTwoNumbers = firstNumber.plus(secondNumber) // (4)

println("($firstNumber + $secondNumber) = $sumOfTwoNumbers") // (5)
}

El ejemplo anterior muestra un formato que usamos en Develou para comentar ejemplos que
requieren ser explicados en detalle.

Esto significa, agregar un comentario de línea al inicio para darle un título al objetivo del
programa. Y luego agregar comentarios en la misma línea de las sentencias, para nombrar los
pasos que estamos dando.

Este formato nos permite dar contexto a las descripciones de nuestros tutoriales, con el fin de
referirnos al código por los números escritos. Elementos que el compilador de IntelliJ IDEA
ignorará (el IDE acentúa su diferencia al código compilable, con letra cursiva y color gris claro):
 Comentarios Multilínea

Si requieres insertar un comentario que contenga múltiples línea, entonces abre con barra-
asterisco, escribe n cantidad de líneas y cierra con asterisco-barra (/* ... */).

El compilador ignorará del código compilable todo lo que se encuentre entre estos dos:

/*
* Copyright 2021 James Revelo. Todos los derechos reservados.
* Ver Copyright.txt para más detalles de permisos
*/
package basics

fun main() {
/* Código */
}

En el código anterior se ve como usamos un comentario con múltiples líneas para aplicar un
ejemplo de copyright a un archivo Kotlin.

Si ves que se incluyen muchas líneas, IntelliJ IDEA te permite contraer dichos comentarios para
mejorar la vista. Solo presionas uno de los dos botones de los extremos del comentario para
colapsarlo:

Atajos Para Comentar En IntelliJ IDEA

Claramente IntelliJ IDEA nos provee accesos directos para comentar y descomentar líneas.

Para comentarios de línea ve a Code | Comment with Line Comment para comentar la línea
donde se encuentre el cursor. O usa el atajo de teclado equivalente que se muestra al final. En
nuestro caso es Ctrl+/:
 Homólogamente, para comentar/descomentar una línea con un comentario de múltiples líneas,
selecciona la línea y dirígete a Code | Comment with Block Comment o usa el shortcut
enunciado al final. En nuestra situación es la conjugación Ctrl+Mayús+/.

Comentarios TODO

Los comentarios TODO te permiten marcar partes de tu código con tareas que deseas realizar en
un futuro.

Para añadirlos en IntelliJ IDEA, antepón la palabra TODO en un comentario de única línea y luego
escribe la tarea a realizar.

fun main() {
// TODO: Crear test unitario del controlador de "animales"
}

Otra forma de añadirlo es tipear todo y seleccionar el constructor emergente que te ofrece el IDE:
 Si deseas crear un comentario TODO con múltiples líneas, entonces usa el patrón FIXME en el
comentario.

fun main() {
//FIXME Completar característica "listar animales":
// - Crear controlador para lista de animales
// - Crear comandos
// - Crear repositorio de animales
}

Ambos tipos de todos pueden ser vistos y accedidos a través de la ventana de herramientas
llamada TODO. Si la abres, verás la ubicación de todos los comentarios y podrás navegar hacia
ellos para comenzar a completar sus instrucciones.

Documentación Con KDoc

Kotlin posee un formato de documentación similar a Javadoc llamado KDoc. Este usa etiquetas
de bloque denotadas con @ para especificar diferentes aspectos de la entidad documentada y
Markdown para marcado en línea.

La forma de crear un comentario con KDoc es iniciándolo con /** y terminándolo con */. Por
ejemplo, generemos la documentación para la cabecera de una clase:

/**
* Representa a los animales del zoo
*
* @property name Nombre del animal
* @property type Clasificación taxonomica del animal
* @property age Edad en meses del animal
*
 * @author James Revelo
* @constructor Crea un nuevo animal
*/
class Animal(val name: String, val type: String, val age: Int)

Puedes explorar más sobre su sintaxis y etiquetas aquí.

Y también puedes estudiar sobre la herramienta de generación del archivo de documentación,

llamada Dokka.