Menu

Conventions de codage et outils, 2003-2004



Langage de programmation
Allocation dynamique
Conventions de nommage
Documentation du code
Arborescence des répertoires
Héritage
Thread
Compilation/linkage
Test unitaires
CVS: gestion de versions

Langage de programmation: C/C++

Cette année on code en C++ avec des classes et même des templates et la stl !

Allocation dynamique

Etant donné que nous faisons de l'embarqué, les allocation dynamiques sont interdites!
Une exception pourra être faite si il n'y a vraiment pas d'aute moyen, mais dans ce cas, l'allocation devra être restreinte aux fonctions d'un seul fichier et devra être caché à l'utilisateur. Ce dernier ne doit pas avoir à appeler une fonction qui libèrera la mémoire.
Les new ne sont autorisés que dans les constructeurs des classes de type Manager qui sont des singletons (une seule instance de cette classe existe en mémoire), et pour la construction des singletons.

Conventions de nommages

Le code est écrit en anglais. Les commentaires le sont aussi sauf dérogation (description compliquée d'algorithmes...)

Fonctions:

verbeDAction
Ex: wait(...), getPicture(), goForward(...)

Structures/classes/types:

NomDeLaStructure. Les noms de types commencent par une majuscule à l'exception des types pointeurs qui sont précédés par la lettre p
Une liste de types de bases étendus serat disponible dans le fichier robotTypes.h
Ex: Events, typedef Events* pEvents, typedef enum Color{...} Color, Millimeter, Radian, Degre;

Les types communs à tout le code du robot sont dans src/include/robotTypes.h

Variables:

nomVariable, les noms de variables doivent être explicites
Ex: ballColor, paletNumber

Constantes:

MODULE_NOM_DE_LA_CONSTANTE. Les constantes sont définies de préférence par des static const qui sont beaucoup plus typés que des #define
Ex: static const PaletNumber PALET_NUMBER_MAX = 12;

Les constantes communes à tout le code du robot (dimensions du robot, du terrain...) sont dans src/include/robotConst.h

Les macros communes à tout le code du robot (min, max,...) sont dans src/include/robotMacro.h

Fichiers:

nomFichier.cpp / nomFichier.h. Que les fichiers soient codés en C ou C++ ils auront l'extension cpp. Tous les fichiers header auront l'extension .h
Ex: move.h, hctl.cpp, movePosition.cpp

Doc

Commentez au mieux vos fonctions, et décrivez en détails ce que font vos fonctions publiques (celles qui sont declarées dans les .h du repertoire src/include).
Nous utilisons
doxygen pour générer la doc.
Les mots clés standard sont les suivants:
- /** : pour commencer la description d'un fichier, d'une fonction ou d'une structure - @brief + courte description
- @param + nom du paramètre + description du paramètre
- @return + description des valeurs retournées par la fonction
- @see + liste des fonctions relatives
- @todo + liste des choses à faire
- @author + nom des auteurs
- @date +date

Ex:
/**
* @brief This function returns the name of an event
*
* Long description : interesting for debug
* @param evt Events
* @return the name of the event
* @todo implement this function
* @see evtGetType
*/
char* evtGetName(Events evt);

Arborescence

./doc : documentation
./doc/html : documentation générée par doxygen
./lib : librairies statiques générées en compilant le contenu de .src. Permet de créer des petits programmes
./so : librairies dynamiques générées en compilant le contenu de .src. Elles sont utilisées par le programme principal et elles évitent de relinker tout le programme comme avec des librairies statiques
./bin : éxécutables
./binSimu : éxécutables permettant de simuler le robot
./src/ : code source
./src/include : interface de chaque module
./src/module/* : répertoire ou sont codés les drivers DRIDAQ et UART
./src/... : composants du robot



Héritage

Toutes les classes du robot devront dériver de class RobotBase qui définit un nom pour la classe et le niveau de debug (verboseLevel). En héritant de cette classe, vous pourrez utiliser les fonctions du type LOG_ERROR("message"), LOG_OK, LOG_DEBUG...
Toutes les classes qui ont besoin d'être réinitialisées à la fin de l'éxécution d'une stratégie devront hériter de class RobotComponent qui est définit la fonction virtuelle void reset() et la fonction bool isInitialized().

Thread

Le but est de minimiser le nombre de threads embarqués dans le robot.
Pour le moment il y en a 3:
class Timer: classe sur laquelle on enregistre des taches périodiques ou qui doivent s'exécuter à une date donnée:
- class Simulator
- class Viewer3D
- class UartBuffer (vérification d'un envoie d'un octet par des microcontroleurs vers la carte UART)
- class Dridaq (vérification que les entrées de la carte dridaq ont changées)

class MovementManager: tache périodique du contrôle des déplacements du robot.
- class Motor (vérification que les moteurs ne forcent pas)
- class Move (régulation des déplacements du robot)
- class RobotPosition (mise à jour de la position du robot)
- callback utilisateur

class IoManager: gestion des messages recus sur les ports UART

Compilation

Les libraires sont compilées de manière dynamique(.so), ce qui permet de gagner du temps pendant la compilation, car il n'est pas nécessaire de relinker le programme principal.

Pour compiler son code:

Le répertoire des sources doit contenir le Makefile générique.
- make clean : efface les .o, .so, *~
- make doc : génère la doc html ave doxygen. Celle-ci est placée dans ./doc/html
- make all : compile tout le code, les tests et la doc.
- make tarsrc : génère un fichier tar.gz du répertoire src.

Tests de non regression

Afin de valider plus facilement le code, chaque classe devra posséder une fonction de validation automatique (sans intervention humaine) : bool validate() qui retournera true si le test a réussi (le module ne plante pas même en pleine charge et il retourne les bonnes valeurs) et false sinon.

CVS: gestion de versions

CVS permet de gérer les différentes versions du code, de sauvegarder et récupérer d'anciennes versions.

Rapatrier le code chez soi:

Rapatrier la dernière version:
cd robot2003/src
cvs update -d

Pour rapatrier une version avec un label:

Mettre a jour le code chez soi:

cd robot2003/src
cvs update -d

Sauvegarder ses données sur le serveur:

cd robot2003/src
cvs add filename (si le fichier est n'es pas encore sous cvs)
cvs ci

Merger 2 fichiers modifiés simultanéement:

Poser un label:


Coupe e=m6 2004 - "Sophia Team" : ISIA-ESSI-ESINSA