Comentar el Código... o la Magia de Ponerse en el Lugar del Otro

En el ámbito del desarrollo de Software, se denomina Código Fuente a una secuencia de instrucciones de computador escritas en un lenguaje comprensible por un ser humano, típicamente, como texto. Haciendo la analogía con el mundo real, el Código Fuente es similar a la descripción de un procedimiento. Por ejemplo, consideremos el siguiente procedimiento de control de acceso:

1. Acérquese a la puerta.
2. Digite su número de identificación.
3. Coloque su mano en el lector biométrico.
4. Espere la validación exitosa.
5. En caso de ser exitosa, abra la puerta.
6. En caso contrario, reingrese su código y comience nuevamente desde el paso número 2.

En el caso del Código Fuente, éste describe (similar a un procedimiento) lo que debe hacer el computador para lograr un objetivo. Está diseñado para facilitar el trabajo de los programadores o desarrolladores de software, que son los profesionales responsables de "traducir" las necesidades de los usuarios en Código Fuente. Una vez que el Código Fuente está listo, es traducido en lenguaje de bajo nivel (lenguaje comprensible por el computador) utilizando un Software denominado Compilador. El compilador actúa como un traductor Inglés-Español, por ejemplo, traduciendo desde el lenguaje procedural (Código Fuente) comprensible por un humano (desarrollador), al lenguaje de máquina comprensible por el computador. El resultado del compilador es lo que se denomina un Ejecutable o Aplicación, y es lo que, finalmente, usan las personas.

En términos generales, el Código Fuente siempre va a estar en fase de Desarrollo y/o Mantención. La fase de Desarrollo corresponde a la fase de construcción inicial de una aplicación, es decir, desde cero. La fase de Mantención corresponde a la fase posterior al término de la aplicación y que, básicamente, se dedica a la tarea de corregir pequeños errores e incorporar funcionalidades nuevas a la misma. En este sentido, es importante tener presente que, a menos que se esté desarrollando una tarea y/o una aplicación muy pequeña, siempre el Código Fuente estará siendo manipulado por varios desarrolladores al mismo tiempo. En el mejor de los casos, desarrolladores en una misma ubicación geográfica. En el peor de los casos, desarrolladores distribuidos globalmente.

En cualquiera de las fases, desarrollar Código Fuente requiere tener capacidad lógica, conocer el lenguaje de programación, ser ordenado, metódico y creativo, aunque suene contradictorio. Y, adicionalmente, exige ser capaz de incorporar Comentarios al Código Fuente que permitan aclarar, declarar, ejemplificar y/o documentar alguna condición particular o específica que no sea evidente para un tercero. Incluso, debiera realizarse en aquellos casos en que no participe nadie más en el desarrollo.

Los Comentarios cobran mayor relevancia cuando se está en un proceso de Mantención. En general, la Mantención implica ser capaz de arreglar y/o mejorar algo sin generar nuevos problemas. Haciendo una analogía con el mundo físico, es como intentar cambiar una rueda con el auto andando. La Mantención es una tarea compleja, en especial, para aquellas aplicaciones que han sido desarrollados hace ya mucho tiempo y/o que han sido mantenidos por variadas personas y, peor aún, para aquellos que no tienen ningún tipo de documentación disponible.

Cuando se realiza mantención de un Código Fuente, un desarrollador debería ser capaz de entender la lógica de la aplicación fácilmente. Cualquier detalle, dependencia y/o vinculación que no sea detectada a tiempo, implicaría de inmediato la posibilidad de incorporar nuevos problemas al intentar hacer una corrección.

La primera manera de evitar esto es, como mencioné antes, incorporando Comentarios al Código Fuente. La segunda manera, y más importante aún, es incorporar Comentarios que realmente hagan sentido. Esto, claramente, es lo más difícil de lograr.

Veamos algunos ejemplos.

1. Tiempo Verbal
Es fundamental comprender que al momento de comentar el código fuente, lo que se requiere es describir lo que hace el código (procedimiento), no lo que "yo he decidido hacer", desde el punto de vista del desarrollador. En este contexto, los comentarios, siguientes son incorrectos.

// Recorro el arreglo
for( int i = 0; i < 10; i++ )
...

// Valido el largo del texto
if( sText != null && sText.length() == 0 )
...

La solución consiste en escribir los comentarios anteriores como sigue (aún cuando siguen siendo incorrectos como se describe en el siguiente punto):

// Recorrer el arreglo
// Validar el largo del texto

2. Comentarios con Sentido
Los comentarios deben incorporar información relevante. El comentario siguiente, no entrega ningún antecedente que un desarrollador con algo de experiencia no pueda identificar de inmediato.

// Recorro el arreglo
for( int i = 0; i < 10; i++ )
...

Ahora bien, si recorrer el arreglo anterior es importante, el comentario se debe reescribir adecuadamente:

// Recorrer el arreglo para determinar la fecha
// de ingreso menor de los documentos elegidos
for( int i = 0; i < 10; i++ )
...

3. Inicialización de Variables
Probablemente, el comentario más inútil y más utilizado por los desarrolladores novatos. Cualquiera de las variantes siguientes son innecesarias.

Form oForm = new Form(); // Inicializo la variable

// Inicializar las variables
String name = "";
String region = "";

// Abro la Conexión con la Base de Datos
Connection oConn = db.GetConnection();

4. Comentar Omisiones Controladas
Durante el desarrollo del Código Fuente, hay condiciones que serán ignoradas. Las razones pueden ser variadas, pero, en aquellos casos en que no son obvias, debe dejarse por explícito la omisión. A continuación, algunos ejemplos.

switch( status) {
  case 1:
    mes = "Encendido";
    break;
  case 0:
    //Fall-Through - Cualquier otro valor
  default:
    mes = "Apagado";
}

En el caso anterior, se deja explícito que, cualquier valor distinto de 1, se considera "Apagado".

try {
  :
  :
}
catch( Exception ex ) {
  // Dummy, no se hace nada
}

En el caso anterior, se deja explícito que no se va a procesar ninguna Excepción ocurrida durante el procesamiento. Si no se incluye el comentario, un desarrollador podría considerar relevante el procesamiento de alguna excepción y romper el flujo normal del programa.

5. Yo Pensé que Tú Pensaste
El uso e inclusión de estructuras de datos, bibliotecas de terceros, etc., es casi una obligación hoy en día. Gracias a fundaciones como Apache y al movimiento OpenSource, no es necesario partir desde cero al momento de realizar un desarrollo, sin embargo, si es necesario documentar las razones por las cuales se realizaron las elecciones correspondientes.

Veamos un ejemplo para el uso de una estructura de datos determinada.

// Inicializo el Hashtable
Hashtable oHT<..., ...> = new Hashtable<..., ...>();

Un programador inexperto, podría considerar que es mejor usar un Hashmap que un Hashtable porque "básicamente proveen las mismas operaciones". El comentario, debe ser explícito para aclarar esto.

// Se usa un Hashtable para evitar problemas de
// concurrencia en el acceso a los datos
Hashtable oHT<..., ...> = new Hashtable<..., ...>();

En el caso de las bibliotecas de terceros, la situación es la misma.

// Recuperar la interfaz del Logger
static Logger log = Logger.getLogger(...);

En este caso, se requiere declarar que se está utilizando una versión de Log4j determinada.

// Se utiliza Log4j 2, para evitar problemas de rendimiento
static Logger log = LogManager.getLogger(...);

En el ejemplo anterior, probablemente el ambiente de desarrollo (IDE) declararía que el método no está presente con otras versiones, sin embargo, es necesario incorporar este tipo de comentarios cuando hay una razón explícita para utilizar una biblioteca determinada.

En términos generales, lo más importante al momento de incorporar Comentarios al Código Fuente, es tener presente que deben ser útiles para otra persona. No son comentarios para mí (desde el punto de vista del desarrollador) y, al momento de escribirlos, es fundamental ser capaz de ponerse en el lugar del otro, el que, probablemente, mantendrá el Código Fuente.

Como indican Kernighan & Plauger en el libro The Elements of Programming Style:

"No documentes código malo - reescríbelo"

Y, como dice Steve McConnell, en su libro Code Complete:

"Buenos comentarios no repiten el código ni lo explican. Clarifican su intención. Los comentarios debieran explicar, en un nivel de abstracción más alto que el código, lo que se está haciendo".

Incorporar comentarios en el Código Fuente es un proceso importante y, en muchos casos, el proceso de reflexión requerido para determinar qué y cómo incluir un comentario puede ser una ayuda, incluso, para determinar si el código está bueno o malo.

Tweet