This page contains outdated information and needs to be updated. Refer to the English language page.
Freecivs Stilvägledning[]
Om man vill koda Freeciv och få sina patchar antagna så hjälper det att följa några enkla stilregler. Ja, några av dessa är en aning petiga, men krig utkämpas över de fånigaste saker...
- Freeciv är skrivet i C (förutom BEOS-klienten). Detta innebär att C++-drag som "//"-kommentarer och variabeldeklarationer som inte är i början av block är förbjudna.
- Använd K&R-indragsstil med indrag 2 (vid tveksamhet, använd "indent -kr -i2 -l77"). Men man ska inte ändra stilen på kodstycken som man inte ändrar på annat sätt eller skapar. Här är de viktigaste egenskaperna:
- den största tillåtna radlängden är 77 tecken
- blanksteg infogas före och efter operatorer ("int i, j, k;" i stället för "int i,j,k;" och "if (foo <= bar) c = a + b;" i stället för "if(foo<=bar) c=a+b;")
- funktionsklammern skall stå i den första kolonnen:
int foo()
{
return 0;
}
- i stället för
int foo() {
return 0;
}
- tabavståndet skall vara 8
- En tom rad ska sättas mellan 2 åtskilda kodstycken.
Kommentarer[]
- Varje funktion ska ha ett kommentarhuvud. Det ska vara ovanför funktionens implementering, inte prototypen:
/************************************************************************* funktionsbeskrivningen ska vara här all användbar information såsom vad som anropar funktionen med mera skapa _inte_ en ny funktion utan någon form av kommentar *************************************************************************/
int the_function_starts_here(int value)
{
...
}
- Enradskommentarer: Kommentaren ska vara rätt indragen och stå ovanför koden som kommenteas:
int x; /* Detta är en enradskommentar */ x = 3;
- Flerradskommentarer: Stjärnor ska stå framför kommentarraden:
/* Detta är en * flerradskommentar * bla bla bla */
- Kommentarer i deklarationer. Om man behöver kommentera en variabeldeklaration så ska det göras så här:
struct foo {
int bar; /* bar används för ....
* att ..... ska */
int blah; /* blah används för .... */
};
- Kommentarer i villkorssatser: Om man behöver en kommentar för att visa programflödet så ska den stå nedanför if eller else:
if(is_barbarian(pplayer)) {
x++;
} else {
/* Om inte barbar ... */
x--;
}
- Kommentarer till översättare står före strängen som är märkt med N_(), _() eller Q_() och har förstavelsen "TRANS:". Dessa kommentarer kopieras till översättningsfilerna. De ska användas närhelst man tycker att översättarna kan behöva lite mer information:
/* TRANS: Översätt inte "commandname". */
printf(_("commandname <arg> [-o <optarg>]"));
Deklarera variabler[]
- Variabler kan tilldelas ett värde vid initialiseringen:
int foo(struct unit *punit)
{
int x = punit->x;
int foo = x;
char *blah;
...
}
- Efter variabeldeklarationerna ska det vara en tom rad före resten av funktionskroppen.
- Sammanfoga deklarationer: Variabler behöver inte dekrareras på var sin rad. De ska dock endast sammanfogas om de har liknande användning.
int foo(struct city *pcity)
{
int i, j, k;
int total, cost;
int build = pcity->shield_stock;
}
Klamrar[]
- Ytterligare klamrar på upprepningar: Lägg märke till att *_iterate_end; ska stå på samma rad som slutklammern:
unit_list_iterate(pcity->units_supported, punit) {
kill(punit);
} unit_list_iterate_end;
- I switchsatser skall klamrar bara sättas där de behövs, till exempel för att skydda variabler.
- Klamrar skall användas efter villkorssatser:
if (x == 3) {
return;
}
- och
if (x == 3) {
return 1;
} else {
return 0;
}
- inte
if (x == 3) return 1; /* DÅLIGT! */
Annat[]
- Om ett tomt block behövs så ska man sätta en förklarnde kommentar i det:
while(*i++) {
/* nothing */
}
- Ordna inkluderingsfiler konsekvent: Alla systeminkluderingsfiler ska stå först, inom <> och i bokstavsordning. Sedan ska alla freecivinkluderingsfiler stå inom "" och ordnade efter katalog (common, server, ...) och sedan i bokstavsordning. Det ska vara en tom rad mellan styckena. Detta hjälper till att undvika dubbla inkluderingar.
- Om man använder systemberoende funktioner så ska man inte lägga till #ifdef __CRAY__ eller liknande. Man ska i stället skriva ett prov för funktionen i både configure.in och configure.ac och använda ett meningsfullt makronamn i källkoden.
- Globala funktioner ska alltid ha prototyper i lämpliga inkluderingsfiler. Lokala funktioner ska alltid deklareras som statiska. För att upptäcka detta och några andra problem skall man använda följande varningsargument för gcc; "-Wall -Wpointer-arith -Wcast-align -Wmissing-prototypes -Wmissing-declarations -Wstrict-prototypes -Wnested-externs".
- Om man skickar patchar så ska man använda "diff -u" (eller "diff -r -u" eller "cvs diff -u"). Se How to Contribute för ytterligare upplysningar. Man ska även ge patcharna beskrivande namn (till exempel "fix-foo-0.diff", men inte "freeciv.diff").
- När man kör "diff" för en patch så ska man se till att utesluta onödiga filer genom att använda kommandoradsargumentet "-X" för programmet "diff":
% diff -ruN -Xdiff_ignore freeciv_c freeciv > /tmp/fix-foo-0.diff
- En föreslagen "diff_ignore"-fil följer med Freeciv.