When a comment changes the meaningCuando un comentario cambia el significado

Looking at foreign source code for the first time, is like an archaeologist finding a lost civilization.

Unless we have on a rosseta stone (or better still, we know the language lost), the unique form to decode it is «test and error».

Recent days, had an unusual fail in my application fingerprint reader. Sometimes saving the template of the fingerprint in the database, I wanted to save a second or third reading, but still kept the first. In addition, I identified only 1 fingerprint of all saved.

Reviewing the original example from development kit, I found the reason of the error and my confusion.

While I was developing C# code of fingerprint reader, I found a method interacting with the database, but declared in an illegal place. A few months ago, the first thing I did was to move that portion of code to another file that corresponds to my «Model» layer. The line that caused my confusion was as follows:

public int identify(ref int score, ref AxGrFingerXLib.AxGrFingerXCtrl grfingerx)
{
    GRConstants result;
    int id;
    SqlDataReader rs;
    TTemplate tptRef; // <= FAIL HERE

    // More code...
}

At the head of the method was a comment that said something like «compare the reader’s template against all the templates obtained from the database». Therefore, I assumed that «TTemplate tptRef» meant «Fingerprint of reference». I do not know what concept of «measure of reference» was the programmer’s example, but for me, a rule or a weight is a unit of reference. Ie «My template is compared with yours».

However, the programmer for example, «Footprint of reference» mean «each of the templates in the database». That is to say: «My template in each turn of the cycle is the same in the database and compared with your reading».

That simple change of meaning, ruined the code. Now, after long having made these changes, I got to understand how this method works only reading the source code, but I would have been forced to investigate more thoroughly «where the fingerprint reading was clogged».

I learned how important it is to look at all the interpretations that may have documents or comments. If we are the ones that document, then avoid a breakdown that could change the meaning.

Mirar código ajeno por primera vez, es como un arqueólogo encontrando una civilización perdida.

A menos que contemos con una piedra rosseta (o mejor aún, conozcamos el lenguaje perdido), la única forma de decodificarlo es «al tanteo».

Los últimos días, había experimentado una falla inusual en mi aplicación lectora de huellas. A veces guardando el «template» de la huella en la base de datos, quería guardar una segunda o tercera lectura, pero se seguía guardando el primero. Además, solo me identificaba 1 huella de todas las guardadas.

Volviendo al ejemplo que venía junto al kit de desarrollo, encontré el motivo, tanto del fallo como de mi confusión.

Mientras desarrollaba el código del lector de huellas en C#, encontré un método trabajaba con la base de datos, pero en un lugar donde no debía. Lo primero que hice hace meses, fue separar esa porción de código a otro archivo qu corresponde a mi capa de «Modelo». La linea de la discordia fue la siguiente:

public int identify(ref int score, ref AxGrFingerXLib.AxGrFingerXCtrl grfingerx)
{
    GRConstants result;
    int id;
    SqlDataReader rs;
    TTemplate tptRef; // <= EL FALLO ESTA ACA

    // Más código...
}

El encabezado del método tenía un comentario que decía algo así como "compara el template de la lectura con todos los templates obtenidos desde la base de datos". Por lo tanto, asumí que "TTemplate tptRef" significaba "Huella de referencia". No sé que concepto de "medida de referencia" tuvo el programador del ejemplo, pero para mí, una regla o un peso es una unidad de medida de referencia. Es decir "Mi template se compara con todos los tuyos".

Sin embargo, para el programador del ejemplo, "Huella de referencia" significaba "cada uno de los templates de la base de datos". Es decir, "Mi template en cada vuelta del ciclo, será el mismo de la base de datos y se comparará con tu lectura".

Ese simple cambio de significado, me echó a perder el código. Ahora después de mucho tiempo de haber hecho esos cambios, logré entender el funcionamiento de ese método solo leyendo el código, pero de no haber usado como "medida de referencia" el código del ejemplo sin modificar, me habría visto obligado a investigar a fondo "donde se quedaba pegado en la lectura de la huella".

La moraleja es entonces, fijarse en todas las interpretaciones que pueda tener la documentación o los comentarios. Si somos nosotros los que documentamos, debemos evitar que un detalle tan pequeño pueda cambiarle todo el sentido.

Un comentario sobre “When a comment changes the meaningCuando un comentario cambia el significado

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Este sitio usa Akismet para reducir el spam. Aprende cómo se procesan los datos de tus comentarios.