[safa] C API - Algunas reglas y General Pupose APIs

[Dario Rodriguez]

Hola gente,

En particular, este mensaje está dirigido a los desarrolladores de la API en C.

Mientras por el otro lado vamos haciendo la lógica en diversos scripts, iremos preparando la API para funcionar. Como todavía no tenemos un Handbook sobre formato del código, tomen estas directivas iniciales, y algo de sentido común:

1. Primero los includes del sistema, y siempre en el *.c a menos que sea estrictamente necesario incluir en el *.h, imaginen en cuántos lugares podría incluirse ese *.h, y luego multipliquen el espacio temporal necesario, el trabajo del preprocesador. No tengo ganas de compilar por media hora solo porque a alguien se le ocurre ser pragmático con esto
   
2. Los tipos de retorno de las funciones siempre encima de ellas, así es más legible
   
3. Los tipos estructurados se declaran solo una vez, en la cabecera de interfaz, a menos que sean de uso particular del módulo
   
4. No exportamos funciones de uso interno, vale decir que esas funciones deben declararse explícitamente como 'static'
5. La identación es de TABs de 8 caracteres de ancho. NO ESPACIOS. Si esto es excesivo, usaremos 6 o 4, pero quiero evitar el anidamiento excesivo, y esta me parece una buena estrategia.
6. No usamos typedefs para tipos estructurados no punteros, exceptuando quizá punteros a funciones. El motivo es simple, y lo considero una práctica más que buena: No ayudan en nada.
   
   Piensen acerca de un código como el siguiente:
   
   vlisto_t node;
   
   Es realmente horrible ¿Qué se supone que sea vlisto_t? En cambio:
   
   struct virtual_list_object *node;
   
   Sí que es capaz de describir con precisión de qué estamos hablando. No se trata de escribir menos o más "encapsulado", sino de realmente saber qué es lo que estamos haciendo.
7. No usamos la horribleEstructuraCamello. No es clara. Los programadores de C son_capaces_de_expresarse_mejor usando guiones.
8. No es necesario usar un nombre como:
   
   int tempvar_f_int_usg; /* temporal variable for internal usage */
   
   Que es espeluznante e ilegible. Es mucho mejor usar:
   
   int tmp;
   
   o un nombre completo, al fin y al cabo C admite hasta 256 caracteres en el nombre del identificador.
   
   int some_temporal_chunk;
9. Please, usamos comentarios al estilo C, no C++. Primero porque estamos escribiendo C, segundo porque es mucho más coherente tener solo un tipo de comentarios, tercero porque hay compiladores que no soportan el tipo de comentarios de C++.
10. En los prototipos de funciones, preferimos usar nombres de variables, aunque C no los requiere, porque agrega información útil al lector.
11. Nunca nunca haces un comentario que no hace más que traducir para humanos:
    
    /* if the character is not 'S'...
     */
    if (the_character != 'S')
    
    Si alguien no conoce el lenguaje C, entonces no debe estar leyendo fuentes en C, debe estar aprendiendo el lenguaje. El código debe ser lo suficientemente claro como para evitar estos comentarios.
12. Los GOTO no son malos. De hecho, el compilador creará jumps similares para las estructuras condicionales, solo que necesitamos un buen motivo para usar un GOTO en el código. El caso preciso es cuando una función necesita algo de 'cleanup' de memoria asignada o una rutina de salida, y tenemos múltiples puntos potenciales de salida. En ese caso, es mucho mejor escribir la rutina de salida una sola vez, y usar un GOTO:
    
    int
    a_function(int a) {
    
        int result = 0;
        char *buffer = malloc(SIZE);
    
        if (!buffer)
            return -ENOMEM;
    
        if (condition1) {
            while (loop1) {
                ...
            }
            result = 1;
            goto out;
        }
        ...
    out:
        free(buffer);
        return result;
    }
    
    
13. Tu forma de escribir C delata tu forma de escribir. Usa espacios luego de una coma y no pases de las 100 columnas, usa párrafos de forma sensata, sé ordenado.

Por ahora, comenzaremos con APIs de propósito general, como 'messages' (safa/gp/messages.h) y 'dynamiclist' (safa/gp/dynamiclist.h)

Si alguno tiene ganas de empezar, avise y les digo mas o menos que es lo que vamos a ir armando. Cada API obviamente tiene que tener sus tests definidos una vez aceptada.

Y seamos super exigentes con el código C, porque es el definitivo.

Saludos,

--

Dario