Scripting standard

Psaní libovolného kódu je často velmi subjektivní a o tom, jak má vypadat zdrojový byly sepsány stohy knih. V mnohých věcech panují věčné rozpory a neexistuje jedno konkrétní správné řešení. Sphere v tomto není výjimkou a její laxní syntaxe dovoluje zapsat stejný kód různými způsoby. Na jedné věci se však shodnou naprosto všichni vývojáři - ať už se nakonec rozhodneme pro jakoukoliv variantu zápisu kódu, je naprosto klíčové, aby všichni vývojáři jednoho projektu dodržovali shodné zásady. Přestože můžou tyto podmínky působit jako malichernost, desetiletí softwarového vývoje naprosto jednoznačně ukazují, že nejde o nuanci, ale že disciplína vývojářů v udržování homogenního, přehledného kódu vede k obrovským rozdílům ve výsledné kvalitě samotného kódu a k nižšímu výskytu chyb. V dobře organizovaném kódu se daleko lépe orientuje, je srozumitelnější a tedy je i další rozšiřování už existujícího kódu rychlejší.

Prosím tedy neberte následující řádky pouze jako doporučení, ale jako zcela závazný požadavek, který váše skripty musí splňovat. Porušení kteréhokoliv z níže uvedených bodů bude při kontrole vašich změn považován za zásadní chybu a změny vám budou navráceny k přepracování.

Coding Standard

1. K odsazování používáme 2 mezery, ne tabulátor!!
2. Používáme závorkové notace tam, kde to jde. Příklady:

arg(localVar)
var(globalVar)
def_defnameVariable
sysMessage("text v zavorkach a uvozovkach")
tag(tagName,"value")
tag(tagName2,<arg(localVar)>)

1. Pokud má nějaká základní sphere funkce více argumentů, nepíšeme za čárkou mezeru, například u tagu:

tag(name, <arg(value)>) // spatne
tag(name,<arg(value)>)  // spravne

1. V kódu dáváme přednost anglickým jménům, vyjma jmen funkcí volaných přímo hráči a dalším textům viditelným hráči.
2. Jména funkcí:
   • Jména pomocných funkcí, která nejsou určena k přímému volání ze hry (hráčem či GM), započínejte prefixem f_
   • U funkcí spojených s nějakým objektem zmiňte jednoznačně daný objekt ve jménu funkce hned za prefixem, příklad:

[itemdef i_fallingDoor]
...
[function f_fallingDoor_riseUp]

1. • Poslední částí jména funkce by měl být stručný, ovšem výstižný popis toho, co daná funkce dělá. Jméno by mělo být dostatečně sebedokumentující, aby neyblo nutné psát další komentář objasňující, co se v dané funkci vlastně děje (f_fallingDoor_riseUp)
2. jména předmětů:
   • Vždy začínají prefixem i_
   • Jsou-li vytvořena v kontextu nějakého širšího konceptu (quest, dobývání, dungeon, summoni ...), následuje za prefixem jasný (společný) identifikátor tohoto konceptu
   • Poslední částí jména předmětu je jasný popis předmětu (tree, memory, counter, gateGuard ...)
3. jména v questových definicích:
   • Každý quest má přiřazený jasný identifikátor, jako např. gq002. Tento identifikátor se musí objevit hned za prefixem definice předmětů, funkcí, dialogů a dalších definic spojených s daným questem

[itemdef i_gq002_item]
...
[function f_gq002_doingThis]
...
[defnames d_def_gq002]
def_gq002_firstDefname  value

[chardef c_gq002_characterDefName]
...

1. Komentujte kód tam, kde je to třeba!
   • Vždy dokumentujte vstupy do funkcí, které je třeba volat - tedy argumenty funkcí. Pro víceúčelové (sdílené) funkce je také vhodné zmínit, nad čím je třeba funkci volat (někdy je třeba vyvolat funkci nad předmětem, cílem targetu, hráčem vyvolávajícím danou událost apod.)

// this function is doing this and that
// argv(0) - this is some object ID
// argv(1) - this is some value, having THIS and THAT effect on the function
// argv(2) - this is a text message displayed when THIS and THAT happens
// ...
[function f_context_doingSomething]
...

1. • Definice komentujte vždy *před* samotnou definicí, ne až v bloku kódu vyhrazeném pro danou definici (optimalizace výkonu)
   • Pakliže cítíte, že musíte psát komentář, zvažte, zda by nebylo vhodné použít raději další funkci, která svým jménem jasně vyjádří, oč jde, a zakryje nějaký komplikovaný implementační detail. Přidávání dalších sebepopisujících funkcí do kódu namísto několikanásobně zanořených podmínek zpřehledňuje čitelnost kódu a redukuje riziko chyby
2. Výpočty v kódu *závorkujte*! Sphere nemá definovanou prioritu operátorů násobení, dělení apodobně. <3+4*5> není totéž jako <4*5+3>. Korektní zápis by měl být <3+(4*5)>. Není však třeba závorkovat výpočty, kde k chybě ani dojít nemůže, např. <1+2+3-4>, <2*3*4>, <10/3> apod.
3. Neupravujte globálně špatně formátovaný kód, vznik chyby je vysoký. Pokud se ovšem v nějakém kódu více vrtáte, pak je vhodné jej rovnou i přeformátovat. Odsazení bývá zcela bezpečné, změny ve voláních však otestujte!