Skip to content

Normalisation du code

Jump to bottom
Valentin VERGEZ edited this page Feb 9, 2019 · 15 revisions

Langue utilisée

Anglais majoritairement.
Noms de fonctions et de variables en anglais.
Commentaires explicatifs en Français (pour qu'ils soient compris de tous). Anglais acceptable pour des petits commentaires, si facilement compréhensible par tous.

Indentations

Norme d'indentation Allman

void a_function(void)
{
    if (x == y)
    {
        something1();
        something2();
    }
    else
    {
        somethingelse1();
        somethingelse2();
    }
    finalthing();
}

Tabulation avec des espaces, 4 espace la tabulation.

Essayer de ne pas dépasser les 80 caractères en largeur (cas des tests de IF à rallonge, appel de fonctions à rallonge). Certains éditeurs affichent une ligne pour marquer les 80 caractères, c'est le cas de Sublime Text en configuration initiale. Sinon, View/Ruler/80
C'est une bonne pratique pour éviter de se fatiguer les yeux, ne jamais avoir à scroller sur la droite et pouvoir spliter l'écran en deux fichiers raisonnablement lisibles (sans side-bar).

Quand vous revenez à la ligne sur un IF ou appel de fonctions, essayez d'aligner les expressions où arguments sur le premier (à la tabulation près).

Switch case - bonne pratique

Quand un case ne se termine pas par un break ou un return, le fil d’exécution continuera dans le case suivant. Si c'est volontaire, ajoutez simplement un commentaire /* FALLTRHOUGH */ pour faciliter la relecture du code.

Nommage des variables et fonctions

Variables et fonctions en lowerCamelCase.
Ajout d'un préfixe sur les variables spéciales, constantes et énumérations en capitales :

global int 	    g_globalVariable 
private: int    m_classMemberVariable   
static int      s_staticVariable  
const int       c_constantVariable  
#define         DEFINE_CONSTANT_VARIABLE
enum            name { ENUM_A = constexpr , ENUM_2 = constexpr , ... }

Commentaires et en-têtes

En-têtes de fichiers obligatoires, format Doxygen.
En-tête de fonctions recommandées, format Doxygen.

Exemple d'en-tête 👍 :

/**
 * \file main.c
 * \brief Programme de tests.
 * \author Franck.H
 * \version 0.1
 * \date 11 septembre 2007
 *
 * Programme de test pour l'objet de gestion des chaînes de caractères Str_t.
 *
 */

Commentaires d'explication en Français. Anglais acceptable pour des petits commentaires facilement compréhensibles par tous.

Tuto Doxygen sur developpez.com

Protection auto-inclusion

#ifndef NOMDUPACKAGE_NOMDUFICHIER_H
#define NOMDUPACKAGE_NOMDUFICHIER_H

    {some code here}
    
#endif // NOMDUPACKAGE_NOMDUFICHIER_H

CMakeLists

Une seule règle, regrouper les instructions par targets :

add_executable(action_node 
    src/action.cpp
    src/action_node.cpp
)
target_link_libraries(action_node ${catkin_LIBRARIES} )
add_dependencies(action_node manager_msg_gencpp)
set_target_properties(action_node PROPERTIES COMPILE_FLAGS "-g3 -std=c++0x")

Nommage des fichiers

Les fichiers qui contiennent les fonctions main() de vos nœuds doivent finir par le suffixe _node et respecter le nommage des nœuds ros, soit lowercase et underscore uniquement.
Les fichiers de classes doivent porter le nom de la classe, le nom de classe étant normalement écrit en UpperCamelCase (commençant par une majuscule).
On utilise lowerCamelCase pour nommer les autres fichiers de manière générale, comme les collections de fonctions par exemple.

Ce qui donne :

simple_publisher_node.cpp
MyClass.cpp
AnotherClass.cpp
turtlesim_node.cpp
functionCollection.cpp
gridUtils.cpp

README

Un README par package, vous pouvez utiliser la syntaxe Mardown plus jolie quand on regarde sur GitHub (ou directement éditer le README sur GitHub). Cette page wiki est rédigée en Markdown ...
Markdown Basics & Markdown Enhanced for GitHub
Ou en format court et syntéthique : MASTERING MARKDOWN

Il doit contenir la liste des noeuds et launchfiles et si possible une description, le reste c'est à votre guise.

Exemple :

example_package
==============
Package d'exemple

Description
-----------
Un package bidon avec un README bien verbeux, codé avec la syntaxe Markdown. Oui, j'ai du temps à perdre ...

Noeuds
------
* hello_world : affiche un `Hello World ! ` et quitte
* i_am_ready : indique `I'm Ready` en boucle jusqu'à ce que t'ai compris ! (et même après en fait :neutral_face:)

Launchfiles
-----------
* `helloWorld.launch` : lance le noeud hello_world, ni plus ni moins
* `iMReady.launch` : lance le noeud i_am_ready, ni plus ni moins

Scripts
-------
* `scriptExample.sh` : script d'exemple permettant de faire un jolie `Hello World ! `

Avancement
----------
* [x] Rédiger un README
* [ ] Faire marcher tout ça, :laughing:

Ce qui donnera cet exemple de README

Clone this wiki locally