Menu informatique
Architecture
Conventions de codage
Doc du code source
Methodologie
L'annee prochaine...
Programmes
Code des matchs
backup
|
Conventions de codage et outils, 2002-2003
Langage de programmation
Allocation dynamique
Conventions de nommage
Documentation du code
Arborescence des répertoires
Compilation/linkage
Test unitaires
CVS: gestion de versions
Langage de programmation: C/C++
Nous utilisons un compilateur C++, mais nous codons à la manière C, en utilisant quelques fonctionnalites de C++. Les interfaces entre modules sont en C avec éventuellement les fonctionnalités C++ suivantes: valeurs par defaut, exceptions. Mais elles ne contiennent pas de classes.
A l'interieur d'un module, les classes sont autorisées mais pas recommandées...
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.
Conventions de nommages
Le code est écrit en anglais. Les commentaires le sont aussi sauf dérogation (description compliquée d'algorithmes...)
Fonctions:
module_verbeDAction
Ex: events_wait(...), camera_getPicture(), move_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;
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;
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 dynamiques générées en compilant le contenu de .src
./bin : éxécutables
./src/ : code source
./src/include : interface de chaque module
./src/robot : code embarqué dans le robot
./src/host : code pour les applications déportées (sur Duvel) : simulateur, télécommande
./src/common : code commun à robot et host (lib géométrique)
./src/robot/module : code source d'un module (.cpp et .h)
./src/robot/module/subModule : si un module peut être décliné en plusieurs versions( réelle, simulée,...), son code se trouve exclusivement dans ses sous modules
Chaque module doit comprote une fonction d'initialisation definie comme suit:
int module_loadAndInit(char* moduleName);
Qui retourne 0 en cas de succes et un code d'erreur sinon.
Si un module peut etre definie de plusieurs manieres : simu, reel,...
chaque version doit etre placee dans un sous repertoire du module.
De plus dans ce cas, dans le repertoire du module, on doit trouver
les fichiers suivants (remplacez module par le nom du module:
./module/module.cpp et ./module/moduleStruct.h
- moduleStruct.h definit la structure typedef struct ModuleStruct {}
qui reprend la liste des fonctions de ./include/module.h
De plus, il definit le pointeur sur fonction :
typedef ModuleStruct (*GetModuleStruct)(void);
Une fonction de ce type appelee getModuleStruct()
doit etre definie dans chaque sous repertoire correspondant aux differentes version du module et doit
remplir la liste de pointeurs sur fonctions declaree dans la precedente structure.
- module.cpp reprend la liste des functions de module.h et les appel au
travers de la structure de pointeurs sur fonction.
De plus, la fonction int module_loadAndInit(char* moduleName) charge
la librairie dynamique correspondante et l'initialise.
Voir l'exemple dans ../demo/dynamicLib pour plus de details ;)
Compilation
Les libraires sont compilées de manière dynamique(.so), ce qui permet par la suite de choisir quel type de sous module on souhaite exécuter : réel/simulé, ...
Pour compiler son code:
Le repertoire des sources doit contenir le Makefile générique.
- make clean : efface les .o, .so, *~
- make test : compile le code et le programme de validation du module
- 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.
Tests de non regression
Afin de valider plus facilement le code, chaque module devra posseder une fonction de validation automatique (sans intervention humaine) : Boolean abréviationmoduleValidate() (Boolean evtValidate();) qui retournera 1 si le test a réussi (le module ne plante pas même en pleine charge et il retourne les bonnes valeurs) et 0 sinon.
Le module devra également contenir un fichier validateMain.cpp qui contiendra un main capable de lancer la validation.
Voir l'exemple dans ../demo/dynamicLib pour plus de details ;)
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:
|