No Comment cómo escribir los comentarios en C

Si sois de los "no escribo comentarios. Son una pérdida de tiempo", paraos aquí. Ya se que no os voy a poder convencer (ni me importa).

Para todos los demás: el comentario es vuestro mejor amigo, nunca os abandonará. El comentario es la última barrera entre el entender y el no entender "¿que tenía en mente cuando escribí ese programa hace un año?". El comentario es vuestra demostración de respeto para vuestros compañeros de trabajo: tarde o temprano, alguno de ellos pondrá sus manos sobre vuestro software y el número de maldiciones que os envíe será inversamente proporcional a la cantidad (y calidad) de los comentarios que habéis escrito.

Claro, hay varias maneras de comentar el código, que van desde "Absolute No Comment" al "auto-explicativo con la adición de comentarios" (bueno, esto es un poco exagerado...), con todos los casos intermedios posibles ...

Vamos a hacer una pequeña demostración: vamos a fijarnos en tres maneras de escribir una función para leer un dispositivo de control industrial (se trata, en el Caso 3, de un código real que escribí hace unos años: Para este ejemplo he cambiado solo algunos nombres). Que se tenga en cuenta que los tres códigos son prácticamente idénticos, aun que la lectura de una impresión completamente diferente ...

Caso 1: código Absolute No Comment

int smsg(S_dev *p)
{
    if (p->msg) {
        p->btx[0]=p->msg;
        if (!sndch(p->ch,(char *)p->btx,(size_t)1))
            return(-1);
        p->msg=0;
    }
    return(0);
}

como se puede ver no hay ningún comentario, el código es (por decirlo suavemente) críptico, y se ahorra en todo: nombres, espacios, líneas: que nunca pase que alguien pueda entender lo que está escrito. Para los maníacos del secretismo.

Caso 2: código auto-explicativo

int sendMessageToDevDummy(
    S_dev_dummy *p_devdum)
{
    if (p_devdum->msg_to_send != 0) {
        p_devdum->buffer_tx[0] = p_devdum->msg_to_send;

        if (! send_char_to_dev(p_devdum->channel_tx, (char*)p_devdum->buffer_tx, (size_t)1))
            return(-1);

        p_devdum->msg_to_send = 0;
    }

    return(0);
}

como se puede ver no hay ningún comentario, pero el código es auto-explicativo y no se ahorra en nada. Los nombres son elegidos para obtener la máxima claridad. Para quien no ama los comentarios, pero quiere que quede claro a toda costa.

Caso 3: código claro y comentado

/* sendMessage()
 * envia un mensaje al device dummy
 */
int sendMessage(
    S_dev_dummy *dev)
{
    // espero los mensajes a enviar
    if (dev->msg_2snd) {
        // copio el mensaje en el buffer de transmision
        dev->buf_tx[0] = dev->msg_2snd;

        // envio el mensaje
        if (! send_char_2dev(dev->chan_tx, (char *)dev->buf_tx, (size_t)1))
            return(-1);

        // libero el semaforo de transmision
        dev->msg_2snd = 0;
    }

    return(0);
}

como se puede ver, hay una cabecera (que debería ampliarse para las funciones importantes) y muchos comentarios breves. El código no es auto-explicativo, pero es lo suficientemente claro. Para comment-lovers.

Es inútil decir que pertenezco a la escuela comment-lovers. Pero también respeto los seguidores del código auto-explicativo. Sobre los señores del Absolute No Comment lo único que puedo decir es ... No Comment. Sin embargo, si os interesa, el Caso 1 no es una exageración, y he visto hasta cosas peores, mejor me callo...

Hasta el próximo post.