Documenter son code (quel que soit le langage utilisé) est important pour plusieurs raisons :
- Afin de permettre une compréhension du code par soi-même (il est peu probable que l'on se souvienne exactement du fonctionnement de son propre code dans quelques mois/années)
- Afin de permettre une compréhension du code par les autres (très utile pour les projets réalisés à plusieurs)
Lisibilité du code
Le code-source doit être facilement lisible par un humain. Pour cela on peut adopter une convention d'écriture et s'y conformer. Il existe de nombreuses conventions avec chacune ses thuriféraires et ses détracteurs (les goûts et couleurs ne se discutent pas). Il existe des raisons plus ou moins rationnelles de préférer une convention plutôt qu'une autre. Pour un projet donné, l'important est de rester homogène : un projet pourra imposer une certaine convention.
Pour toutes les conventions, il est important :
- D'indenter correctement son code afin d'identifier rapidement les différents blocs de code (pour certains langages tel que Python l'indentation est une caractéristique essentielle du code). L'indentation peut être obtenue par des caractères espace ou tabulation selon les conventions. Historiquement on préférait limiter la longueur des lignes en raison des contraintes des terminaux de travail ; de nos jours, l'intérêt est plus limité avec des éditeurs de texte avec retour à la ligne automatique.
- De donner des noms intelligibles au variables locales, champs de classes et noms de classes. Ainsi les noms a, b, c, toto, titi, foo, bar... sont généralement à proscrire.
- De distinguer les noms de classes, les noms de champs et variables et les constantes (par exemple les noms de classes peuvent commencer par une Majuscule, les variables par une minuscule et les constantes peuvent être totalement en MAJUSCULES).
- De ne jamais utiliser des valeurs numériques en dur dans le code : elles doivent être remplacées par une valeur constante avec un nom symbolique ; la déclaration des constantes pouvant être ou non déclarées dans un fichier en-tête selon leur utilité pour des modules externes.
Il existe des outils réalisant l'indentation automatique du code. On peut ainsi utiliser un environnement de développement intégré (IDE tel que Eclipse, Visual Studio Code...) ou alors un utilitaire tel que indent :
indent code.cpp -o corrected_code.cpp
En langage C++, il existe de nombreuses conventions d'écriture :
- Le style GNU encouragé dans les projets GNU
- Le style Kernighan & Ritchie (du nom des créateurs du langage C)
- Le style Berkeley
- Le style d'écriture du noyau Linux
- ... et bien d'autres
La juste dose de commentaire
Le code-source doit être agrémenté d'une juste dose de commentaires. En règle générale, les modules, les classes, méthodes et fonctions doivent être précédées d'un commentaire décrivant leur rôle ainsi que leur usage (signification de chaque paramètre, valeurs attendues pour les paramètres, informations sur la valeur de retour calculée...). Il est conseillé de démarrer ces commentaires par /** pour les distinguer des commentaires locaux.
A l'intérieur des blocs de code, on peut également indiquer des commentaires si le code n'est pas très explicite par lui-même ou si des choix peu évidents ont été réalisés (afin de les expliquer). C'est d'autant plus important pour les algorithmes d'un certain niveau de complexité.
En règle générale, on indique en début de fichier des informations sur l'identité de l'auteur du code ainsi que la licence sous laquelle celui-ci est disponible.
Voici un exemple de programme documenté calculant un nombre de Fibonacci pour un rang précisé par l'utilisateur en utilisant une méthode itérative :
/*
* Copyright 2018 Michel Chilowicz
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* fibo.cpp
* A program computing Fibonacci numbers using a classical iterative method
*
* @author Michel Chilowicz
* @email chilowi@u-pem.fr
* @version 1.0 2018/11/15
* @license Apache License
*/
#include <iostream>
using namespace std;
/* First values of the Fibonacci sequence */
const uint64_t FIBO_0 = 1;
const uint64_t FIBO_1 = 1;
/**
* Swap two references in memory.
*
* @param a first reference
* @param b second reference
*/
template<class T>
void exchange(T& a, T& b) {
T c = a;
a = b;
b = c;
}
/**
* Compute the Fibonacci number of the given rank.
*
* For large ranks, note that the computed Fibonacci number may exceed the
* capacity of the return type uint64_t.
*
* @param n rank whose Fibonacci number is expected
* The rank must be positive or null
* @return the Fibonacci number of rank n
*/
uint64_t fibo(const int n) {
// We keep the two last Fibonacci numbers
// we initialize them with the constant values of fibo(0) and fibo(1)
uint64_t previous = FIBO_0;
uint64_t last = FIBO_1;
if (n == 0) return previous;
else if (n == 1) return last;
else {
for (int i = 2; i < n; i++) {
previous += last;
exchange(previous, last);
}
}
return last;
}
/**
* Entry point of the program.
* We ask the rank of the Fibonacci number the user wants to compute.
* We print the result on the standard output.
* We continue while the user supplies valid positive ranks.
*/
int main() {
while (true) {
cout << "Enter the rank of the Fibonacci number to be computed" << endl;
int rank = -1;
cin >> rank;
if (rank < 0 || cin.fail())
return 0;
else {
auto result = fibo(rank);
cout << "fibo(" << rank << ") = " << result << endl;
}
}
}
Génération d'une documentation
Des outils permettent de générer une documentation depuis le code-source en extrayant les commentaires en tête des classes et méthodes. On pourra citer notamment Doxygen assez utilisé pour le langage C++ (Doxygen est également compatible pour d'autres langages). Doxygen propose une interface graphique (doxywiard) afin de choisir les différentes options de configuration. On peut ainsi choisir de générer une documentation au format HTML avec moteur de recherche, en PDF (en utilisant LaTeX), au format manpage ou alors en fichier RTF. Le style de la documentation peut être personnalisé par exemple en fournissant ses propres feuilles de styles ou logos pour la version HTML.