Buenas prácticas: Comentarios

[Arielo]

Con este tema, comenzaré una serie dedicada a las buenas prácticas de programación.
El primer tema es: COMENTARIOS

Los comentarios son muy importantes en programación.
Lamentablemente, muchos programadores consideran una pérdida de tiempo el comentar los programas. Claro, después lo lamentan cuando tienen que hacerles ampliaciones, correcciones, etc...

La forma de comentar un programa, varía de un lenguaje a otro.

En los primeros BASIC, había que colocar la sentencia REM al principio de la línea:

REM Esto es un comentario BASIC

Todo lo que se escribe después de REM es ignorado, por lo que esta línea no imprimirá nada:

REM Print "Hola!!!"

En BASIC también se acepta la comilla simple ' en reemplazo de REM (en la mayoría de las versiones)

En Python se utiliza el numeral (#). Al igual que en el REM, todo lo que se escribe después del signo es ignorado:

# Esto es un comentario de Python

Si bien los comentarios pueden explicar qué se está haciendo en esa parte del programa

REM Asigna el valor 12 a la variable m
m = 12

es más útil utilizarlos para explicar el porqué se hace esto...

REM m contiene la cantidad de meses del año
m = 12

[Arielo]

Con respecto a los comentarios, es útil utilizarlos al comienzo de cada programa o módulo, de tal forma que sirvan para detallar lo que hace.

Sigo con ejemplo en BASIC:

'-----------------------------------------------
' FECHA.BAS
' VERIFICA SI LA FECHA INGRESADA ES CORRECTA
' Autor: Arielo
' Versión: 1.0
' Fecha: 10/10/2007
'-----------------------------------------------
' Log:
' 10/10/07: Se crea el archivo Fecha.BAS inicial
' 12/10/07: Se arregla el error del 29 de Febrero
'-----------------------------------------------

[Arielo]

También pueden ser utilizados para deshabilitar porciones de código:

Ejemplo 1:

For I = 1 to 50
	 If I = 12 Then Print "Llegué al 12"
	 If I = 25 Then Print "Llegué al 25"
Next I

Ejemplo 2:

For I = 1 to 50
	 If I = 12 Then Print "Llegué al 12"
	 ' If I = 25 Then Print "Llegué al 25"
Next I

En el primer ejemplo, cuando el índice del bucle (La variable I) llegue a valer 12, imprimirá que ha llegado a ese valor.
Y cuando llegue a 25, también indicará que ha alcanzado dicho valor.
Pero, en el segundo ejemplo, al comentar la línea donde se evalúa si I vale 25, ya no nos informará cuando se alcance ese valor, debido a lo que dijimos al principio: todo lo que esté después de REM (o la comilla, como en este caso), es ignorado...