Scripting standard: Porovnání verzí

Verze z 17. 6. 2018, 15:08

Názvosloví

Objekt - character nebo item

Linker - objekt, který se nějakou formou odkazuje na jiný objekt (tag s UID objektu, LINK)

Linkee - objekt, který je jiným předmětem odkazován (jeho UID je uloženo na nějakém Linkeru)

Definice - řádek kódu v hranatých závorkách, jako např. @[function f_name]@, @[chardef c_whatever]@, @[itemdef i_item]@ aj.

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!