Comment nommer les choses ? - Qualité de Développement

Nom de variable expressif — Credits: the_coding_love

camelCase¶

Constantes globales et classes

CONSTANTE_GLOBALE : Les constantes globales doivent utiliser la convention UPPER_SNAKE_CASE (aussi appelé SCREAMING_SNAKE_CASE). Les noms de variables globales doivent être écrites en majuscules, avec les mots séparés par des underscores (_). De manière générale, il est recommandé d’éviter l’utilisation de variables globales. Toute variable susceptible de changer de valeur devrait avoir une portée (scope) limitée (locale) et utiliser la convention camelCase. Les constantes globales sont définies avec const <type> VARIABLE_GLOBALE. L’autre usage de la convention UPPER_SNAKE_CASE est pour les constantes statiques à l’intérieur d’une classe. Par exemple :

class MyClass {
private:
    static const int STATIC_CONST = 100;
}

class Object : Le nom d’une classe utilise UpperCamelCase qui est camelCase mais avec une majuscule au début.

Noms révélateurs d’intention¶

int d; // temps écoulé en jours

Un nom de variable explicite améliore grandement la lisibilité du code. Prenons un exemple où nous nous contentons de renommer les variables. Que fait le code suivant ?

vector<vector<int>> getThem(const vector<vector<int>>& theList) {
    vector<vector<int>> list1;
    
    for(const auto& x : theList) {
        if(x[0] == 4) {
            list1.push_back(x);
        }
    }

    return list1;
}

const int STATUS_VALUE = 0;
const int FLAGGED = 4;

vector<vector<int>> getFlaggedCells(const vector<vector<int>>& gameBoard) {
    vector<vector<int>> flaggedCells;
    
    for(const auto& cell : gameBoard) {
        if(cell[STATUS_VALUE] == FLAGGED) {
            flaggedCells.push_back(cell);
        }
    }

    return flaggedCells;
}

Pour aller plus loin.

class Cell {
private:
    const int mStatusValue = 0;
    const int mFlagged = 4;

    vector<int> values;

public:
    // Constructeur
    //...

    bool isFlagged() {
        return values[mStatusValue] == mFlagged;
    }
};

vector<Cell> getFlaggedCells(const vector<Cell>& gameBoard) {
    vector<Cell> flaggedCells;

    for(const auto& cell : gameBoard) {
        if(cell.isFlagged()) {
            flaggedCells.push_back(cell);
        }
    }

    return flaggedCells;
}

La désinformation¶

vector<Account> accountList;

int controllerForEfficientHandlingOfStrings;
int controllerForEfficientStorageOfStrings;

int a = 1;
if(O == l) {
    a = O1;
}
else {
    l = 01;
}

Noms différents¶

void copyString(string a1, string a2, int length) {
    for (int i = 0; i < length; i++) {
        a2[i] = a1[i];
    }
}

Problème

Évitez d’ajouter des chiffres à la fin des noms de variables pour les différencier. Une alternative plus claire consiste à utiliser des noms explicites qui reflètent leur rôle distinct. Par exemple :

void copyString(string source, string destination, int length) {
    for (int i = 0; i < length; i++) {
        destination[i] = source[i];
    }
}

money;
moneyAmount;

message;
theMessage;

getProductInfo();
getProductData();

class Customer {
    //...
};
class CustomerObject {
    //...
};

Noms prononçables¶

class DtaRcrd102 {
private:
    string genymdhms;
    string modymdhms;
    const string pszqint = "102";
//...
};

Problème

Ne pas utiliser des noms impossibles à prononcer. genymdhms est la date à laquelle l’objet a été gen(éré) et cette date est en y(ears), m(onths), d(ays), h(ours), m(inutes), s(econds). Vous ne pourriez pas communiquer à l’intérieur d’une équipe si vous n’arrivez pas à prononcer les noms de variables. Une solution pour transformer ce code :

class Customer {
private:
    string generationTimeStamp; // Format : yyyy-mm-dd hh:mm:ss
    string modificationTimeStamp; // Format : yyyy-mm-dd hh:mm:ss
    const string recordId = "102";
//...
};

Noms recherchables¶

Imagine un code avec que des variables d’une seule lettre et des nombres fixés qui apparaissent partout et qu’il contient le morceau de code suivant.

for (int j=0; j<34; j++) {
    s += t[j]*4*5;
}

Maintenant, comparez-le à ce même code.

const int NUMBER_OF_TASK_TYPES = 34;
const int WORK_DAYS_PER_WEEK = 5;
const int NUMBER_OF_TASKS_PER_DAY = 4;
int totalCost = 0;
for (int j=0; j < NUMBER_OF_TASKS_TYPES; j++) {
    int dailyCostPerTask = taskCostPerDay[j] * NUMBER_OF_TASKS_PER_DAY;
    int weeklyCostPerTask = dailyCost * WORK_DAYS_PER_WEEK;      
    totalCost += weeklyCostPerTask;
}

Nom commun pour les classes, verbe pour les méthodes¶

Un seul mot par concept¶

Contextualisation¶

Certaines variables ont des noms suffisamment explicites pour être comprises sans contexte, mais ce n’est pas le cas de la plupart. Par exemple, des noms comme firstName, lastName, street, houseNumber, city, state, et zipcode suggèrent clairement qu’ils font référence aux coordonnées d’une personne.

En revanche, tout seul, un nom comme state est beaucoup plus ambigu : il pourrait désigner l’état civil d’une personne, un état d’un objet dans le code, ou encore un état géographique, selon le contexte.

(Ne pas) faire de blagues dans les noms¶

holyHandGrenade pour faire deleteItems, sérieusement ?

Bien sûr ! Tant que les bonnes pratiques sont respectées, un peu d’humour ne tue personne.

Cours

Développer proprement ?

Cours

Comment écrire une fonction ?