Pravidlá kódovania tímu androids
Z RoboCupTP wiki
Obsah |
Štábna kultúra
V nasledovnej časti je definícia štábnej kultúry tímu Androids pre projekt RoboCup 3D. Štábna kultúra zhŕňa základné všeobecné konvencie tvorby a vývoja softvéru a definuje formálnu stránku vývoja v prostredí Eclipse pre aplikácie, ktoré tím vyvíja.
Všeobecné pravidlá a informácie pre projekty
Nasledujúca kapitola zhrnie všeobecné pravidlá pre vývoj a testovanie softvéru. Uvedené pravidlá sú štandardnými konvenciami a riadi sa nimi aj náš tím.
Pomenovanie
Všetky názvy použité pri vývoji ktorejkoľvek časti kódu alebo pomenovania súborov musia byť
v anglickom jazyku.
Element - Pravidlá názvu elementu
Balíky
· Výlučne malé písmená
· Slovná forma podstatného mena
· Názov musí zapadať do logickej štruktúry predchádzajúcich balíkov
Súbory, triedy
· Zložené z podstatných mien
· Každé podslovo začína veľkým písmenom, ostatné písmená sú malé
· Medzi podslovami nie je explicitná medzera (je určená veľkým písmenom ďalšieho podslova)
Metódy
· Prvé podslovo je sloveso, začína malým písmenom
· Zvyšné podslová veľkým písmenom, bez explicitnej medzery
Premenné
· Ak premenná slúži na indexáciu, postačuje jedno písmenové slovo
· Prvé podslovo začína malým písmenon, zvyšné podslová veľkým
Konštanty
· Všetky písmená veľké
· Medzera je určená znakom "_"
Testovanie
Element - Pravidlá názvu elementu
Súbory, triedy
· Názov vychádza z testovanej triedy/súboru, obsahuje naviac na konci slovo Test
Špecifické pravidlá pre vývoj kódu pre agenta JIM
Anotácie V projekte JIM sa používajú okrem základných anotácií aj nasledovné anotácie, ktoré je nutné dodržiavať pre udržanie meta-informácií o kóde.
Anotácia - Použitie
@Bug
· Označenie elementov kódu,
ktoré nepracujú tak, ako majú.
@Problem
· Označenie elementov kódu,
v ktorých sa našiel problém pri prehliadke kódu.
@Refactor
· Označenie elementov kódu,
ktoré je nutné podrobiť refaktoringu.
@ReviewOk
· Označenie elementov kódu, ktoré:
sú dôkladne otestované Unit testami
prešli prehliadkou kódu
boli otestované voči serveru
@UnderConstruction
· Označenie elementov kódu,
ktoré nebudú zasiahnuté prehliadkou kódu.
Komentáre
Pre dodržanie rovnakej kultúry v projekte JIM, do ktorého prispievajú viacerí autori, je potrebnépoužívať nasledovné komentáre. Nastavenie komentárov sa viaže na prostredie Eclipse, ktoré náš tímna vývoj kódu používa.
Element - Obsah
Types
/**
*
* ${file_name}
*
*@Title Jim
*@author $$Author: ${user} $$
*/
Methods
/**
* TODO: Replace with purpose of method. Start with verb.
*
* ${tags}
*/
Špecifické pravidlá pre vývoj kódu pre testovací framework
Vývoj aplikácie Testovací framework podlieha vo všeobecnosti rovnakým princípom, aké už boli v dokumente naznačené. Rozdiel je len vo formálnych pravidlách vývoja kódu a šablón pre používanie komentárov.
Vývoj kódu a komentáre
Vývoj kódu a tvorba komentárov sa riadi nasledovnými pravidlami:
· maximálna dĺžka riadku 80 znakov (štandardná konvencia)
· okomentovaná každá metóda (okrem metód typu getter a setter), trieda podľa šablóny
- komentár môže byť minimálny, je však záväzné kód aspoň minimálne okomentovať
- v prípade triviálnych metód, ktoré dostatočne vyjadrujú funkcionalitu skrze názvy parametrov, nie sú komentáre parametrov ani výstupnej hodnoty nutné
- dôležité pri komentovaní je dbať na to, aby existencia komentáru bola prospešná
Nasledujúca tabuľka zhŕňa elementy a ich nastavenie pre používanie komentárov:
Element - Obsah
Types
/**
* TODO: Replace with a brief purpose of class / interface.
*
* @author ${user}
*
* ${tags}
*/
Methods
/**
* TODO: Replace with a brief purpose of method.
* Start with verb.
*
* @author ${user}
*
* ${tags}
*/
Ostatné
Tím sa zaoberá aj malými úpravami (aktualizáciou) aplikácie RobotMotionEditor. Nakoľko zmeny, ktoré sú v aplikácií vytvorené sú v porovnaní s veľkosťou aplikácie malé, nie je nutné dodatočne štábnu kultúru pre daný projekt špecifikovať.
