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

Los Errores Humanos...

Es un hecho que los sistemas se caen. Para nadie es una sorpresa llegar a un banco, por ejemplo, y encontrarse con situaciones en las cuales la atención y/o el servicio solicitado no está disponible o no puede ser entregado. El aviso a los clientes, siempre, se grafica en con un letrero como el siguiente:


Veamos algunos ejemplos relacionados:

Ejemplo 1. Ayer, en Publimetro, salió una noticia respecto a un nuevo error en el sistema de sirenas de Tsunami de Iquique que ya había tenido problemas en la prueba anterior (ver La Caída del Sistema... o la Salida más Fácil). Esta vez el sistema de sirenas se activó por que "la empresa ncargada de la tecnología estaba haciendo pruebas silenciosas y por un error humano se activó la alarma". 

Ejemplo 2. El 24 de Diciembre de 2012, los servicios de Netflix tuvieron problemas en la distribución de contenido en algunas regiones de Estados Unidos, Canadá y Latinoamérica. Netflix tiene casi toda su infraestructura montada sobre Amazon Web Services (AWS) y los problemas se originaron por la caída de uno de los ELB (Elastic Load Balancing Service) que son utilizados para proveer el servicio. Según fue informado, la caída se debió a un error humano "debido a que un desarrollador eliminó accidentalmente información de estado del ELB que controla la región Este de Estados Unidos". 

Ejemplo 3. El día 3 de Julio del 2012, 52.770 cartolas de clientes del Banco de Chile fueron enviadas erróneamente a otros clientes. Como resultado de esto, la molestia de los receptores fue generalizada por el problema de seguridad que implicaba este error y por la impresión que le puede haber ocasionado a aquellos que les faltaba dinero y la emoción a los que les sobraba. Según fue informado por el Banco, "de acuerdo a la información entregada por nuestro proveedor Xerox de Chile S.A., en el proceso de generación y despacho mediante correo electrónico de las cartolas de cuenta corriente del mes de junio, dicha empresa incurrió en errores al adjuntar a la comunicación cartolas equivocadas".

Algunas observaciones importantes respecto a estos eventos:

1. Primer Ejemplo - Prensa.La información respecto al error sólo ha sido entregada por la prensa. No hay información en ninguna otra parte. Las condiciones (y los montos) de la asignación de la licitación se pueden ver aquí.

2. Segundo Ejemplo - Comunicación.
Amazon y, por consiguiente Netflix, publicaron en sus sitios web reportes informando sobre las causas del error. Estos reportes, denominados Post-mortem por ser, obviamente, realizados después de la falla (algo así como una autopsia) se pueden ver en los siguientes links: Amazon - Summary of the December 24, 2012 Amazon ELB Service Event in the US-East Region y Netflix - A Closer Look At The Christmas Eve Outage.

3. Segundo Ejemplo - Explicación.El reporte provee información detallada del error. Adicionalente, si se lee con detención el reporte de Netflix, se puede acceder a información interesante como los lineamientos generales de la estrategia del 2013 para evitar una situaciones similares, algunos juicios respecto al estado del arte de los servicios en la nube y, a dos clicks de distancia, la liberación como OpenSource de las herramientas de administración desarrolladas y utilizadas por Netflix para administrar sus servicios en un repositorio GitHub (ver repositorio Netflix).

4. Segundo Ejemplo - Oportunidad.
El reporte incluye, como resultado de la declaración de las estrategias y acciones para el 2013 y las causas del error, publicidad respecto a las posiciones (puestos de trabajo) existentes para resolver estos desafíos. En términos simples, una invitación, una oportunidad a partir del problema.

5. Tercer Ejemplo - Responsabilidad.
Conocido el error en el despacho de las cartolas, la solución del Banco fue simple: culpar al Proveedor sin tapujos y, además, abrió un nuevo frente de acción: el del secreto bancario, según el cual, "los depósitos y captaciones de cualquier naturaleza que reciban los bancos están sujetos a secreto bancario y no podrán proporcionarse antecedentes relativos a dichas operaciones sino a su titular o a quien haya sido expresamente autorizado por él o a la persona que lo represente legalmente". Asimismo, establece que quien infrinja esta norma "será sancionado con la pena de reclusión menor en sus grados mínimo a medio".

6. Tercer Ejemplo - Solución.
Además de responsabilizar al proveedor y realizar el reenvío de las cartolas correctas, el Banco aprovechó de enviar un mail a las personas que habían recibido la cartola errónea con el siguiente texto: "Por un error en que incurrió nuestro proveedor en el proceso de despacho de la Cartola Mensual de cuenta corriente del mes de junio usted recibió información que no corresponde a su cuenta, por lo que le agradeceremos eliminar dicha información por cuanto su uso podría generar responsabilidades legales". Este mail generó aún más molestia en los clientes afectados porque, sin ir más lejos, era una amenaza.

Obviamente, el tamaño de las industrias es muy diferente. Las realidades muy diferentes también, sin embargo, no deja de ser interesante la aproximación en la comunicación de Netflix y Amazon al problema. Al final, siempre van a ocurrir problemas, y con declaraciones que transparenten los hechos se genera una información que invita a entender el problema, a compartir espacios de mejora y, en el caso de Netflix, invitar a las personas que quieran trabajar en desafíos como éstos. Si los clientes toman acciones legales o no, aceptan las explicaciones o no, es otro tema, fuera del ámbito de la discusión sobre el problema en sí mismo.

Ahora, al margen de lo anterior, las preguntas realmente importantes son las siguientes:

¿Las personas responsables de los llamados "errores humanos" habrán sido despedidas?
¿La de Amazon si, la de Chile no?
¿La de Chile si, la de Amazon no?
¿Las dos?
¿Sería correcto despedirlas... o desvincularlas como se dice hoy?
¿Es Xerox el único responsable en el error del envío de las cartolas?
¿Se habrá terminado el contrato con Xerox como resultado del error?
¿Qué crees tú?

Tweet