¿Te preguntas cómo escribir buenos comentarios en programación? Documentar el código es una de las partes más importantes dentro del mundo de la programación, porque algo que hoy tienes muy fresco, dentro de un tiempo podrías tener completamente olvidado, y si no lo documentas como es debido, podrías no entender el código.
Cómo escribir buenos comentarios en programación
Una de las cosas que más “pereza” da a los programadores es el tema de los comentarios. Tanto es así, que los alumnos que empiezan a sumergirse en el mundo de la programación llegan a pensar que los comentarios en el código no son útiles, pero ni te imaginas lo importantes que pueden llegar a ser.
En este artículo no solamente te contaremos cómo escribir buenos comentarios en programación, sino que también te hablaremos de su importancia, las reglas y consejos básicas y la sintaxis para los principales lenguajes.
Importancia de los comentarios en un programa
Dentro del maravilloso mundo de la programación nos encontramos con que un comentario es una anotación sobre un código. Son anotaciones significativas para los programadores (que ignoran los compiladores o intérpretes del código), pero que son necesarios de cara a saber exactamente qué hace una parte del código.
¿Por qué son tan importantes los comentarios para documentar los programas? Son cruciales. Si estás picando código, en ese momento recuerdas que hace exactamente cada una de las partes de código que acabas de programar. Pero así que pasan unos días, unas cuantas semanas o años, no recordarás absolutamente nada si no te encargas de documentar bien el código. Tampoco es necesario documentar cada línea, pero sí es importante comentar los bloques de código, que tengan muchas instrucciones y distintas acciones.
Documentando el código podrás hacerlo más “asequible” de cara a terceros, como puede ser una empresa o el cliente final. Podrás explicarle qué hace exactamente cada parte del código, con pequeños recordatorios a lo largo del código (comentarios) en los que inspirarte y que no afectan en absoluto a la ejecución normal del programa, ya que son líneas ignoradas por los compiladores.
Ventajas de un buen uso e inconvenientes de su uso pobre
No debes pensar en el tiempo perdiendo elaborando buenos comentarios, porque es tiempo ganado a lo largo plazo. Ese tiempo que dediques a elaborar buenos comentarios, te permitirá que el día de mañana, si encuentras ese código, vayas a poder recordar exactamente qué es lo que hace cara parte del programa como si fuera ayer cuando lo escribiste.
El objetivo de los comentarios en la programación, es por tanto hacer el código fuente más fácil de entender de cara a su reutilización o mantenimiento. Porque no podemos ver el código únicamente como algo del presente que funciona y que ya no se va a tocar más, porque es posible modificarlo de cara a hacer cambios o mejorarlo siempre que sea necesario. Incluso se podría tomar como base para reutilizar en un futuro, ya que construir código reutilizable es una de las buenas prácticas dentro del mundo de la programación.
El uso pobre de los comentarios no tiene ningún tipo de valor. Un comentario preciso y conciso es más fácil de mantener y entender que uno largo, complejo y repetitivo, que carece de un sentido o de una buena construcción.
Limitaciones de los comentarios (no pueden suplir un mal código)
Los comentarios no pueden suplir un mal código. Es habitual, en algunos programadores, el hecho de comentar partes del código con “comentarios trampa”, hablando acerca de falsas funcionalidades. Los comentarios deben aportar un valor añadido al código, deben hablar de lo que el código hace, sin mentir o exagerar sus posibilidades y funcionalidades.
Por todas estas razones, insistimos tanto en la importancia de comentar el código.
Reglas, consejos y ejemplos de algunos estilos sobre cómo se ponen comentarios
La sintaxis y las reglas para poner comentarios en programación varían dependiendo del lenguaje empleado. Y es importante tener en cuenta también, que los comentarios necesitan un mantenimiento y deben ser actualizados. En el momento en el que añades nuevas funcionalidades o cambias determinadas partes del código que no hacen lo que deberían, deberás especificarlo en los comentarios.
Los comentarios tienen una amplia variedad de usos posibles:
- Para informar de errores. En muchos casos los comentarios se utilizan en el código para informar que una parte del código no hace lo que debería o lo hace, pero no de la manera en qué debería hacerlo.
- Para mejorar el código. Se suele utilizar de cara a mejorar el código fuente, pensando en la las siguientes revisiones del código.
- Para describir el código. El uso más concreto de los comentarios tiene que ver con documentar las partes del programa por medio de descripciones básicas.
- En control de versiones. Los comentarios también se suelen utilizar aunque de distinta manera en los sistemas de control de versiones para indicar las funcionalidades añadidas en cada versión, corregidas, etc.
Son muy fáciles de introducir en los códigos y la sintaxis es diferente dependiendo del lenguaje de programación que se utilice. Es importante también seguir una “filosofía” de comentarios o metodología, sobre todo si se trabaja en equipo, para que los comentarios sigan una misma estructura y no haya problemas para comprenderlos.
Algunos de los ejemplos de cómo se ponen comentarios en programación son los siguientes:
Por lo general, los comentarios tienen un formato de bloque o de fin de línea.
Los comentarios de bloque puede expandirse a varias líneas de texto, por lo que cuentan con un delimitador de inicio y de fin de comentario. Mientras que los e fin de línea, comienzan con un delimitador y continúan hasta al final de esta misma línea de texto, es decir, no necesitan cierre y son de una sola línea.
Algunos de los delimitadores más comunes son /* , */ y //.
Ejemplo de comentario de bloque
/* Este código permite hacer la suma de dos números naturales enteros,
es necesario actualizarlo en el futuro para que trabaje con decimales,
pendiente de revisión */
Ejemplo de comentario de fin de línea
// Ejemplo de suma entre 2 números
Sintaxis para poner comentarios en todos los lenguajes de programación de alto nivel (una línea y varias)
C++: Lenguaje de programación híbrido diseñado a mediados de los años 1080 por Bjarne Stroustrup.
Comentarios de bloque:
/* aquí va el comentario
de varias líneas */
Comentarios en línea con dos barras diagonales:
// esto es un comentario.
C#: es un lenguaje de programación orientado a objetos que ha sido desarrollado y estandarizado por Microsoft.
// Esto es un comentario en C#
C: es un lenguaje de programación desarrollado por Dennis Ritchie entre 1969 y 1972 en los Laboratorios Bell.
Los comentarios en el lenguaje de programación C se pueden hacer por medio de bloques o líneas de código, por ejemplo, /* … */ o //. Ejemplos de uso de los comentarios en C:
printf( «Hello\n» ); // Aquí iría el comentario
/* Este es otro ejemplo de comentario en el lenguaje C
utilizando varias líneas */
En C encontramos otra manera de dejar comentarios, que funciona como en el siguiente ejemplo. // empieza el comentario y \ indica que la siguiente línea, es decir i++; formará parte del comentario.
// comentario \
i++;
Cobol: Lenguaje simbólico, orientado hacia la programación de aplicaciones de gestión. Muy utilizado en banca.
* Este es un comentario en Cobol
CSS: Cascading Style Sheets es el lenguaje utilizado para describir la presentación de documentos HTML o XML. Es muy popular para diseño web.
Puedes utilizar /* y */ para hacer comentario de una línea o de múltiples.
/**
* Este es un comentario en CSS de una o varias líneas
*/
Delphi: es un lenguaje de programación que se creó para agilizar la creación de software basándolo en una programación visual.
En Delphi nos encontramos con distintos tipos de comentarios:
// este es un ejemplo de comentario en línea
{ este es un comentario en bloque
en el lenguaje de Delphi }
(* este es otro comentario
en bloque en Delphi
formado por varias líneas *)
Además, en delphi se pueden anidar comentarios de bloque (pero siempre que no usen el mismo delimitador).
(*
este es un ejemplo de comentario en bloque
{
que contiene otros
comentarios en bloque
}
// o de fin de línea
y que funciona
*)
Ensamblador: es un tipo de programa informático que puede traducir un fichero fuente escrito en lenguaje ensamblador a un fichero objeto (código máquina).
Así se escribe un comentario en lenguaje ensamblador:
;comentario
Fortran: es un lenguaje de programación de alto nivel de propósito general e imperativo, perfectamente adaptado al cálculo numérico y a la computación científica. Se utiliza principalmente en matemáticas.
! Este es un comentario de línea
En Fortran, una línea en blanco también se interpreta como una línea de comentario, lo cual resulta interesante.
GWBASIC: Dialecto del lenguaje de programación BASIC, originalmente para Compaq, desarrollado por Microsoft a partir de lenguaje BÁSICA.
Los comentarios en GWBASIC se escriben de manera completamente distinta a otros lenguajes que trataremos en este artículo.
REM comentario
‘ Comentario
Por ejemplo:
FOR I=1 TO 20 ‘Calcular la velocidad
REM Calcular la velocidad
HTML: Significada Marcado para Hipertextos (HyperText Markup Language). Se considera el elemento de construcción más básico de una página web. Es utilizado para crear y representar visualmente una página web. Determina su contenido.
En HTML tenemos estos dos tipos de comentarios:
<!– comentario en HTML –>
<!–
este es un comentario en código HTML de varias líneas
// –>
Java: Lenguaje de alto nivel, multiplataforma, de propósito general, concurrente y orientado a objetos.
En Java tenemos distintos tipos de comentarios:
// Este es un comentario de línea
/* Este es un comentario
de bloque en Java */
/**
Este comentario será usado por javadoc
*/
JavaScript: Lenguaje de programación interpretado, dialecto del estándar ECMAScript. Se define como un lenguaje orientado a objetos y está basado en prototipos. Además, es imperativo, débilmente tipado y dinámico.
Los comentarios en JavaScript los encontramos de distintas formas:
// Este es un comentario en línea
/* Aquí tenemos un comentario
en bloque */
Matlab: Es una herramienta de software matemático que ofrece a los usuarios un entorno de desarrollo integrado (IDE) junto con un lenguaje de programación propio (lenguaje M). Es muy utilizado en matemáticas.
En MatLab los comentarios van precedidos por %. Es decir, el programa ignora todo lo que vaya con este símbolo por delante. Nada más escribirlos dentro de la herramienta, te aparecerán en color verde.
% este es un comentario en MatLab
Modula-2: Es un lenguaje de programación cuyo autor es Niklaus Wirth, que casualmente es el autor del lenguaje Pascal. Destaca por introducir el concepto de módulo, y de encapsulación.
(* Este es un comentario en Modula-2 *)
Pascal: Es un lenguaje creado por Niklaus Wirth publicado en 1970. Su objetivo fue crear un lenguaje para facilitar el aprendizaje de programación a sus alumnos, utilizando la programación estructurada y estructuración de datos. Todavía hoy en día se utiliza en ciclos y Universidades para empezar a programar, antes que Java.
Los comentarios en Pascal se rigen por las siguiente reglas:
‘ Comentario
Perl: Es s un lenguaje de programación diseñado por Larry Wall en 1987. Toma características del lenguaje C y de muchos otros lenguajes de programación.
#Así se escribe un comentario en Perl
Python: Es un lenguaje de programación interpretado con una sintaxis que favorece al código legible. Es multiparadigma, soporta orientación a objetos, programación imperativa y programación funcional. Es interpretado, usa tipado dinámico y es un lenguaje multiplataforma.
Al igual que en Perl, los comentarios en Python se escriben de esta manera:
#comentario en Python
Ruby: Lenguaje de programación dinámico y de código abierto enfocado sobre todo en la simplicidad y productividad. Posee una elegante sintaxis, natural, fácil de leer y de escribir. Se ha hecho muy popular en los últimos años.
En Ruby tenemos 2 tipos de comentarios:
#comentario de línea
=begin
comentario de bloque
=end
Visual Basic: Lenguaje de programación dirigido por eventos. Ha sido desarrollado por Alan Cooper para Microsoft. Este lenguaje de programación es un dialecto de BASIC con características agregadas.
En Visual Basic puedes escribir comentarios de manera sencilla:
‘comentario en Visual Basic