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