Pravidlá kódovania tímu androids

Štábna kultúra

V nasledovnej časti je definícia štábnej kultúry písania kódu pre projekty Jim, RobocupLibrary a TestFramework. Š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.

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}
              */