El estilo de programación: Comentarios

Muchas veces, nos encontramos con que hemos escrito una expresión muy compleja. Al momento de escribirla, tenemos bien claro qué es lo que hace, porque acabamos de idearla, pero luego de un tiempo, cuando volvemos a leerla puede que no entendamos muy bien qué es lo que quisimos hacer. Para solucionar casos de este tipo, es aconsejable el uso de comentarios y dejar una explicación del razonamiento que hicimos para obtener ese código, o cualquier otro mensaje que resulte útil para quien lo lea.

El uso correcto de comentarios, nombres significativos e indentación favorecen la claridad del código.

Nombres significativos

Cuando creamos un procedimiento o una función, el objetivo es realizar un cálculo o tarea específica, por lo que el nombre que le demos al subprograma creado debe revelar de la mejor manera posible el objeto de su existencia. A la hora de darles nombres a los procedimientos y funciones, se aconseja usar palabras completas y frases que indiquen cuál es la tarea que el subprograma realiza, evitando las abreviaturas. También es recomendable usar verbos que representen la acción por realizar.

// C# - Forma incorrecta de nombrar subprogramas
void calcRet(string fac)
int MCM(int a, int b)

// C# - Forma correcta de nombrar subprogramas
void CalcularRetenciones(string numeroFactura)
int MaximoComunDivisor(int numeroA, int numeroB)

Consistencia de formato
Quizá lo más importante a la hora de escribir código fácil de mantener sea lograr un estilo consistente y estandarizado, y mantener ese estilo en todo el programa. Esto significa que, si escribimos los nombres de variables locales con minúsculas, las constantes con mayúscula y los nombres de los procedimientos usando mayúscula para la primera letra de cada palabra, debemos repetir esa convención siempre. Así, si somos consistentes, alguien que esté familiarizado con la nomenclatura, al leer un identificador, podrá saber fácilmente si se trata de una variable, una constante, o un procedimiento.
Del mismo modo que es bueno adoptar convenciones de nomenclatura, resulta importante la consistencia en el uso de líneas en blanco, de espacios entre los operandos y los operadores en las expresiones, y en la cantidad de espacios usados para las tabulaciones.

COMENTARIOS VS NOMBRES CLAROS
En la actualidad, existe una discusión sobre si se deben usar o no comentarios para explicar qué es lo que hace un procedimiento o función. Algunos sostienen que resulta necesario colocar un comentario, mientras que otros insisten en que, si se necesita explicar una porción de código, es porque resulta muy compleja, y aconsejan reescribirla para que sea más sencilla, separándola en otros procedimientos o funciones si fuera necesario. La segunda postura lleva a un código mucho más claro y mantenible.

Los entornos de programación modernos permiten definir reglas de codificación y luego modifican el código automáticamente a medida que escribimos, de manera que se cumplan las reglas.

CONCLUSIONES

En este capítulo, hemos aprendido uno de los conceptos fundamentales de la programación: la modularización. Como programadores, debemos tener siempre presentes estos conceptos y usarlos al máximo posible. Es preferible tener muchas funciones y procedimientos a tener grandes bloques de código de cientos de líneas. Muchos programadores (entre los que me incluyo) tienen esta regla de oro: si un procedimiento o función no cabe en una página del editor que estamos usando, entonces será necesario dividirlo en procedimientos y funciones más pequeños, porque se está volviendo demasiado largo y, por lo tanto, demasiado complejo.