Coding Style Guide

Coding Style Guide

Avant-propos

L'objectif ici est simple : avoir un code qui ressemble a quelque chose. L'idéal serait que même s'il est mal écrit ou buggé, qu'il soit assez commenté pour qu'on comprenne ce que l'auteur voulait faire et qu'il ne rebute pas l'éventuel sauveur qui tenterait le corriger.

Pour cela nous devons rédiger des conventions communes de rédaction de code et de commentaires que nous nous efforcerons de respecter.

Conventions de codage

Casse

• Fonctions, variables ou attributs : en minuscule, mots séparés par des underscores (ex : "ma_fonction")
• Constantes : en majuscules, mots séparés par de underscores (ex : "MA_CONSTANTE")
• Classes : en upper Camel Case (ex : "MaClasse")
• Méthodes : en lower Camel Case (ex : "maMéthode")

Commentaires

Nous suivrons ici le format utilisé par Java, qui est très bien parsé par Doxygen (entre autres) :

/**
  * Commentaire de la méthode
  * 
  * @param toto Paramètre qui sert à des trucs 
  *
  * \todo Bar
  * 
  * @return foo
  */

Chaque méthode DOIT être commentée ainsi que son corps (dans la mesure de l'utile). Notons que les commentaires dans le code seront de la forme /* Mon commentaire */

Lorsque vous rédigerez un commentaire, veillez à suivre les règles suivantes :

• Omettez les parenthèses quand vous vous référez à une fonction/méthode. Parce que cela peut porter à confusion si une méthode est surchargée, il est préférable de n'utiliser que son nom (ex : "maMéthode" au lieu de "maMéthode()")
• Utilisez en priorité des phrases courtes, commençant par un verbe pour décrire une méthode/fonction. Il n'y a aucun problème à avoir un commentaire bref mais précis, au contraire !
• Préférer l'usage de "cette/ce" au lieu de "une/un" lorsqu'on se réfère à l'instance actuelle d'une classe.

Mise en forme du code

• Indentation par des tabulations
• Les lignes ne devrait pas être trop longues (~ 80 caractères) et être aérées pour faciliter la lecture
• Le nom des variables et des méthodes doit être parlant (en anglais?)

Exemple de code : void ma_fonction() { int x = 5;

    if(!x == 6)
        faire_un_truc();
    else {
        encore_un_truc();

        while(x > 0) {
            --x;
            puts("toto");
        }
    }
}