Remarques sur les labos

notes.md

Remarques générales sur les labos

Dans l'ensemble vous faites du bon travail. Le code est minimaliste, propre et souvent fonctionnel.

Rappelez-vous que c'est le résultat qui compte. Donc si vous avez un joli code mais qu'il ne passe pas les tests, vous perdez des points.

Voici quelques points d'amélioration utiles pour les futures labos.

En-tête de programme

La plupart d'entre-vous oublie d'ajouter un en-tête en haut du fichier programme. Avant d'inclure les bibliothèques (#include <stdio.h>), tout en haut des fichiers, vous devez écrire un petit commentaire pour expliquer ce que fait le programme. Voici un exemple en français concernant le labo-04 :

/**
 * Calcul du prix d'un PCB.
 * Ce programme calcul le prix d'un circuit imprimé tenant 
 * compte de ses dimensions, de son nombre de couches et de
 * la quantité de composants soudés dessus.
 * 
 * Le programme prends sur les arguments, dans l'ordre : 
 * 1. La largeur
 * 2. La longueur
 * 3. Le nombre de couche
 * 4. Le nombre de résistances
 * 5. Le nombre de diodes
 * 6. Le nombre de condensateurs
 * 
 * Voici un exemple d'utilisation typique : 
 * 
 * $ ./pcb 120 320 2 4 5 6
 * Devis pour réalisation de PCB
 * -----------------------------
 * 
 * Largeur du PCB en cm :     12
 * Longueur du PCB en cm :    32
 * Couche(s) :                 2
 * Nombre de diodes :          4
 * Nombre condensateurs :      5
 * Nombre de résistances :     6
 * 
 * +-----------------+------+-------+--------+
 * | ÉLEMENT         | QTÉ. |   PU  |   PT   |
 * |-----------------+------+-------+--------|
 * | PCB (cm2)       |  384 |  0.10 |  38.40 |
 * | COUCHE(S)       |    2 |  0.05 |  38.40 |
 * | VERNIS          |  768 |  0.01 |   7.68 |
 * | DIODE           |    4 |  0.75 |   3.00 |
 * | CONDENSATEUR    |    5 |  1.00 |   5.00 |
 * | RÉSISTANCE(x10) |    1 |  1.00 |   1.00 |
 * |-----------------+------+-------+--------|
 * |                       TOTAL HT |  93.48 |
 * |                            TVA |   7.48 |
 * |                      TOTAL TTC | 100.96 |
 * +--------------------------------+--------+
 */

Réduire le scope des variables

Pour accroître la lisibilité du code et minimiser les erreurs, il est de coutume de réduire la visibilité des variables en ne les déclarant que là ou elles sont utilisées. Voici un mauvais exemple:

int main(int argc, char * argv[]) {
    int foo; 
    printf("Hello");
    if (argc < 2) abort();
    foo = 2; 
}

Et voici le même exemple mais avec foo déclaré au bon endroit :

int main(int argc, char * argv[]) {
    printf("Hello");
    if (argc < 2) abort();
    int foo = 2; 
}

Noms des variables

Utilisez un nom de variable dont la longueur est proportionnelle à son scope. Autrement dit, plus une variable est générale, plus son nom doit être spécifique.

Voici un mauvais exemple :

int main(int argc, char * argv[]) {
    int a; 
    printf("Saisir votre age :");
    if (scanf("%d", &a) != 1) abort();
    printf("Votre age est %d\n", a);
    for (int nombre_de_bougies = 0; nombre_de_bougies < a; nombre_de_bougies++) {
        printf("1 Bougie\n"); 
    }
}

Et voici un meilleur exemple :

int main(int argc, char * argv[]) {
    int age; 
    printf("Saisir votre age :");
    if (scanf("%d", &age) != 1) abort();
    printf("Votre age est %d\n", age);
    for (int i = 0; i < age; i++) {
        printf("1 Bougie\n"); 
    }
}

Des commentaires utiles

Souvent vos commentaires décrivent ce que le code fait. Un commentaire doit avoir une valeur ajoutée. Les commentaires dans le code suivant sont inutiles :

int main(int argc, char * argv[]) {
    int age; // Variable pour stocker l'age
    printf("Saisir votre age :"); 
    if (scanf("%d", &age) != 1) abort(); // Quitte le programme si erreur
    printf("Votre age est %d\n", age);
    for (int i = 0; i < age; i++) {
        printf("1 Bougie\n"); // Affiche "1 Bougie"
    }
}

Marquer les constantes

Si vos variables ne sont plus destinées à changer. Vous indiquez cela avec le mot clé const :

const int the_answer = 42;

Instruction ternaire

Au lieu du code suivant :

if (foo > 30) 
{
    bar = 2;
} 
else 
{
    bar = 3;
}

Préférez l'utilisation de l'instruction ternaire :

bar = foo > 30 ? 2 : 3;

Des lignes de 80 caractères

Évitez les lignes trop longues. Essayez de garder des lignes d'environ 80 caractères de long.

Une seule source de vérité

Évitez d'utiliser à plusieurs endroit différent une information qui pourrait être groupée à un seul endroit.

Voici un mauvais exemple :

// Test le troisième argument
if (argc < 2 || sscanf(argv[3], "%d") != 1) {
    printf("L'argument 3 est invalide\n");
    abort();
}

Et voici une meilleure écriture où la valeur 3 est regroupée à un seul endroit. Notez aussi que le commentaire inutile a été retiré car il comprenait le mot troisième directement lié à la valeur de arg :

int arg = 3;
if (argc < arg - 1 || sscanf(argv[arg], "%d") != 1) {
    printf("L'argument %d est invalide\n", arg);
    abort();
}