Un code source lisible ! pardi !

Dans la programmation, nous avons une grande liberté concernant la manière dont on écrit du code, c’est ce qui pour moi rend ce domaine si passionnant. Mais il arrive que d’autres personnes aient à lire celui-ci que ça soit dans le cadre d’un travail en équipe, d’un projet open source ou d’une reprise de projet. Il se peut même que vous ayez à ouvrir un code source à vous vieux de quelques années ! Le problème dans cette liberté c’est que si le développeur en question n’a pas pris le soin d’écrire correctement son code, je vous garantis de longues heures extraordinaires à tenter de comprendre tous les mystères du projet !

Mais pour alléger certaines souffrances, suivre certaines règles dans l’édition d’un code devient essentiel. Cela permet d’éviter de longues heures de prise de tête à vous et a votre entourage :). Et comme ici on aime ne pas se prendre la tête, on va voir comment écrire du code propre ! c’est parti !

Alors en effet, suivre des règles dans l’écriture de son code est aussi une prise de tête, mais celui-ci est minime comparé à devoir décrypté un projet en entier mal écrit, mal commenté, mal documenté, mal ce que vous voulez !

Alors un petit effort et voyons comme améliorer la lisibilité de votre code source !

Les conventions de nommage

Écrire quelque chose de lisible, veut dire par la même occasion écrire quelque chose qui a du sens et c’est dans les noms de tout ce que vous déclarez dans un code qu’il faut faire attention. Les développeurs utilisent ce qu’on appelle des conventions de nommage, cela permet d’identifier directement le rôle d’un élément de programmation par son nom. Si en lisant tous simplement le code, vous arrivez à décrire son fonctionnement (sans passer 3 heures dessus), c’est que c’est bien fait !

OK, voyons un exemple concret :

int a = 0;
int b = 2;
int c = mp(a,b);

L’exemple est un peu exagéré, car je n’ai pas mis tout le reste du programme, mais est-ce que vous voyez à quoi sert ce bout de code ?

Maintenant, imaginons que ce code soit ça :

int nombre1 = 0;
int nombre2 = 2;
int resultat = multiplier(nombre1, nombre2);

Le code se passe de commentaire, 🙂 et ça fait exactement la même chose que celui d’en haut ! On multiplie « nombre1 » avec « nombre2 » et on récupère le résultat dans la variable « résultat ».

C’est bête, mais cela vous montre l’importance de bien nommer ses éléments et de suivre une convention pour rendre plus facile la lecture d’un code. Vous imaginez si un projet en entier était écrit comme le premier exemple 8-O.

Chaque équipe a sa propre manière d’écrire son code, lister toutes les règles ici serait impossible, mais on retrouve quand même des grands principes, des règles qu’on applique pratiquement partout :

Chaque variable et chaque fonction doit décrire aussi précisément que possible son rôle dans le programme.

Pour les variables temporaires qui ne sert seulement aux boucles, on utilise généralement « i », « j », « k » et plus en fonctions du nombre de boucles qu’il y a. pourquoi « i » ? « i » signifie index et sert généralement en mathématique lorsqu’on fait une itération.

Les variables, objets , fonctions, attribut d’une classe et méthode d’une classe doivent commencer par une lettre minuscule, ne doivent pas dépasser plus de 4 mots et doivent être attachées sans espaces ni symboles. Les premières lettres des mots qui suivent le premier mot doivent être en majuscule.

int heuresPayee;
string adresseDuCandidat;

Pour les classes et les interfaces, la même règle que celles des variables et autres s’applique, simplement, la première lettre et elle aussi en majuscule. Je mets personnellement les structures dans cette même règle.

Pour les méthodes et les fonctions, il est courant d’utiliser un verbe dans le nom.

Pour les constantes et les macros, ils sont écrits tout en majuscule. S’il est composé de plusieurs mots, on les sépare avec des underscores (« _ »).

const string ADRESSE_DU_CANDIDAT;

Voilà avec ces quelques règles toutes simples, vous pouvez déjà écrire du code lisible, ces règles en plus de pouvoir identifier le rôle des éléments, permettent d’un coup d’œil de voir quelles sont les variables, les constantes et les classes avec ce système de majuscule.

J’utilise aussi d’autres règles perso, comme nommer une variable temporaire tmp quand elle me sert juste de tampon pour une opération. Je mets aussi « _ » dans le nom des attributs d’une classe pour pouvoir les différencier d’une variable normale et je nomme mes variables de retour généralement ret.

Chacun a sa préférence pour le reste, le but est de pouvoir identifier rapidement ce que fait tel truc dans le code, mais les règles citées si dessus sont appliquées par pratiquement tout le monde.

L’indentation

Les noms c’est important, mais la façon dont on espace le code est aussi importante. L’indentation, c’est le fait d’ajouter des espaces ou des tabulations avant une ligne de code de façon à mettre en évidence un bloc de code.

int multiplier(int nombre1,int nombre2){
int ret = 0;
if (nombre1 > 0 && nombre2 > 0) {
ret = nombre1 * nombre2;
} else {
ret = -1;
}
return ret;
}

vs

int multiplier(int nombre1,int nombre2){
	int ret = 0;
		if (nombre1 > 0 && nombre2 > 0) {
		ret = nombre1 * nombre2;
	} else {
		ret = -1;
	}
	return ret;
}

Plus il y a de niveaux, plus l’indentation est forte. Une autre règle simple, mais efficace permettant de distinguer les imbrications de code et la hiérarchie. Les IDE de nos jours le font automatiquement, mais si vous le faites manuellement, l’indentation se fait en appuyant sur la touche TAB.

Les commentaires

Les commentaires sont bien sûr, l’un des meilleurs moyens pour pouvoir comprendre un code source, mais attention à ne pas en abuser. Même si l’on dit qu’un code source n’a jamais assez de commentaires, je trouve que trop de commentaires alourdissent la lisibilité du code, je parle de rajouter 3 paragraphes de commentaire sur chaque ligne de code !

Les commentaires servent surtout à expliquer le fonctionnement d’un bloc de code et à quoi ça sert. On les utilise aussi systématiquement avant chaque début de fonctions et de classe, ce qui permet d’expliquer leurs rôles dans le code, d’ailleurs on les appelle les commentaires de classe et grâce à elle, on peut générer une documentation. Enfin, les développeurs s’en servent parfois pour mettre des tâches à faire qu’on appelle des TODO, cela permet de revenir directement sur le code en question à modifier.

/**
 * Fonction qui va effectuer une multiplication sur les deux paramètres
 * la fonction ne permet pas la multiplication de nombres négatifs
 * @param nombre1 Premier facteur
 * @param nombre2 Deuxième facteur
 * @return Le résultat de la multiplication ou -1 si les deux paramètres sont négatifs
 */
int multiplier(int nombre1,int nombre2){
	int ret = 0;
		if (nombre1 > 0 && nombre2 > 0) {
		ret = nombre1 * nombre2;
	} else { // Si les deux nombres sont négatifs, renvoi le code erreur -1
		ret = -1;
	}
	return ret;
}

Remarque, on dit aussi qu’un bon code source se passe de commentaire grâce notamment aux conventions de nommages, mais rajouter des commentaires sur un bon code source n’est jamais inutile, c’est la cerise sur le gâteau !

Et toi, quelle règle utilises-tu pour améliorer la lisibilité de ton code 😉 ?

A++ 🙂