home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 September / PCWELT_9_2006.ISO / pcwsoft / Freeciv-2.0.8-win32-gtk2-setup.exe / doc / sv / CodingStyle.sv < prev    next >
Encoding:
Text File  |  2005-10-13  |  5.9 KB  |  201 lines
  1. ===========================================================================
  2.  Freecivs Stilv├ñgledning
  3. ===========================================================================
  4.  
  5. Om man vill koda Freeciv och f├Ñ sina patchar antagna s├Ñ hj├ñlper det
  6. att f├╢lja n├Ñgra enkla stilregler. Ja, n├Ñgra av dessa ├ñr en aning
  7. petiga, men krig utk├ñmpas ├╢ver de f├Ñnigaste saker...
  8.  
  9. - Freeciv ├ñr skrivet i C (f├╢rutom BEOS-klienten). Detta inneb├ñr att
  10.   C++-drag som "//"-kommentarer och variabeldeklarationer som inte ├ñr
  11.   i b├╢rjan av block ├ñr f├╢rbjudna.
  12.  
  13. - Anv├ñnd K&R-indragsstil med indrag 2 (vid tveksamhet, anv├ñnd
  14.   "indent -kr -i2 -l77"). Men man ska inte ├ñndra stilen p├Ñ kodstycken
  15.   som man inte ├ñndrar p├Ñ annat s├ñtt eller skapar. H├ñr ├ñr de viktigaste
  16.   egenskaperna:
  17.     - den st├╢rsta till├Ñtna radl├ñngden ├ñr 77 tecken
  18.     - blanksteg infogas f├╢re och efter operatorer ("int i, j, k;" i
  19.       st├ñllet f├╢r "int i,j,k;" och "if (foo <= bar) c = a + b;" i
  20.       st├ñllet f├╢r "if(foo<=bar) c=a+b;")
  21.     - funktionsklammern skall st├Ñ i den f├╢rsta kolonnen:
  22.         int foo()
  23.         {
  24.           return 0;
  25.         }
  26.       i st├ñllet f├╢r
  27.         int foo() {
  28.           return 0;
  29.         }
  30.     - tabavst├Ñndet skall vara 8
  31.  
  32. - En tom rad ska s├ñttas mellan 2 ├Ñtskilda kodstycken.
  33.  
  34. ================================
  35.  Kommentarer
  36. ================================
  37.  
  38. - Varje funktion ska ha ett kommentarhuvud. Det ska vara ovanf├╢r
  39.   funktionens implementering, inte prototypen:
  40.  
  41. /*************************************************************************
  42.  funktionsbeskrivningen ska vara h├ñr
  43.  all anv├ñndbar information s├Ñsom vad som anropar funktionen med mera
  44.  skapa _inte_ en ny funktion utan n├Ñgon form av kommentar
  45. *************************************************************************/
  46.  
  47. int the_function_starts_here(int value) 
  48. {
  49.   ...
  50. }
  51.  
  52. - Enradskommentarer: Kommentaren ska vara r├ñtt indragen och st├Ñ
  53.   ovanf├╢r koden som kommenteas:
  54.  
  55.   int x;
  56.  
  57.   /* Detta ├ñr en enradskommentar */
  58.   x = 3;
  59.  
  60. - Flerradskommentarer: Stj├ñrnor ska st├Ñ framf├╢r kommentarraden:
  61.  
  62.   /* Detta ├ñr en
  63.    * flerradskommentar 
  64.    * bla bla bla */
  65.  
  66. - Kommentarer i deklarationer. Om man beh├╢ver kommentera en
  67.   variabeldeklaration s├Ñ ska det g├╢ras s├Ñ h├ñr:
  68.  
  69.   struct foo {
  70.     int bar;                    /* bar anv├ñnds f├╢r ....
  71.                                  * att ..... ska */
  72.     int blah;                   /* blah anv├ñnds f├╢r .... */
  73.   };
  74.  
  75. - Kommentarer i villkorssatser: Om man beh├╢ver en kommentar f├╢r att
  76.   visa programfl├╢det s├Ñ ska den st├Ñ nedanf├╢r if eller else:
  77.  
  78.   if(is_barbarian(pplayer)) {
  79.     x++;
  80.   } else {
  81.     /* Om inte barbar ... */
  82.     x--;
  83.   }
  84.  
  85. - Kommentarer till ├╢vers├ñttare st├Ñr f├╢re str├ñngen som ├ñr m├ñrkt med
  86.   N_(), _() eller Q_() och har f├╢rstavelsen "TRANS:". Dessa
  87.   kommentarer kopieras till ├╢vers├ñttningsfilerna. De ska anv├ñndas
  88.   n├ñrhelst man tycker att ├╢vers├ñttarna kan beh├╢va lite mer
  89.   information:
  90.  
  91.     /* TRANS: ├ûvers├ñtt inte "commandname". */
  92.     printf(_("commandname <arg> [-o <optarg>]"));
  93.  
  94. ================================
  95.  Deklarera variabler
  96. ================================
  97.  
  98. - Variabler kan tilldelas ett v├ñrde vid initialiseringen:
  99.  
  100. int foo(struct unit *punit)
  101. {
  102.   int x = punit->x;
  103.   int foo = x;
  104.   char *blah;
  105.  
  106.   ...
  107. }
  108.  
  109. - Efter variabeldeklarationerna ska det vara en tom rad f├╢re resten av
  110.   funktionskroppen.
  111.  
  112. - Sammanfoga deklarationer: Variabler beh├╢ver inte dekrareras p├Ñ var
  113.   sin rad. De ska dock endast sammanfogas om de har liknande
  114.   anv├ñndning.
  115.  
  116. int foo(struct city *pcity)
  117. {
  118.   int i, j, k;
  119.   int total, cost;
  120.   int build = pcity->shield_stock;
  121. }
  122.  
  123. ================================
  124.  Klamrar
  125. ================================
  126.  
  127. - Ytterligare klamrar p├Ñ upprepningar: L├ñgg m├ñrke till att
  128.   *_iterate_end; ska st├Ñ p├Ñ samma rad som slutklammern:
  129.  
  130.   unit_list_iterate(pcity->units_supported, punit) {
  131.     kill(punit);
  132.   } unit_list_iterate_end;
  133.  
  134. - I switchsatser skall klamrar bara s├ñttas d├ñr de beh├╢vs, till exempel
  135.   f├╢r att skydda variabler.
  136.  
  137. - Klammrar skall anv├ñndas efter villkorssatser:
  138.  
  139.   if (x == 3) {
  140.     return;
  141.   }
  142.  
  143.  och 
  144.  
  145.   if (x == 3) {
  146.     return 1;
  147.   } else {
  148.     return 0;
  149.   }
  150.  
  151.  inte
  152.  
  153.   if (x == 3)
  154.     return 1;  /* D├àLIGT! */
  155.  
  156. ================================
  157.  Annat
  158. ================================
  159.  
  160. - Om ett tomt block beh├╢vs s├Ñ ska man s├ñtta en f├╢rklarnde kommentar i
  161.   det:
  162.  
  163.   while(*i++) {
  164.     /* nothing */
  165.   }
  166.  
  167. - Ordna inkluderingsfiler konsekvent: Alla systeminkluderingsfiler ska
  168.   st├Ñ f├╢rst, inom <> och i bokstavsordning. Sedan ska alla
  169.   freecivinkluderingsfiler st├Ñ inom "" och ordnade efter katalog
  170.   (common, server, ...) och sedan i bokstavsordning. Det ska vara en
  171.   tom rad mellan styckena. Detta hj├ñlper till att undvika dubbla
  172.   inkluderingar.
  173.  
  174. - Om man anv├ñnder systemberoende funktioner s├Ñ ska man inte l├ñgga till
  175.   #ifdef __CRAY__ eller liknande. Man ska i st├ñllet skriva ett prov
  176.   f├╢r funktionen i b├Ñde configure.in och configure.ac och anv├ñnda ett
  177.   meningsfullt makronamn i k├ñllkoden.
  178.  
  179. - Globala funktioner ska alltid ha prototyper i l├ñmpliga
  180.   inkluderingsfiler. Lokala funktioner ska alltid deklareras som
  181.   statiska. F├╢r att uppt├ñcka detta och n├Ñgra andra problem skall man
  182.   anv├ñnda f├╢ljande varningsargument f├╢r gcc; "-Wall -Wpointer-arith
  183.   -Wcast-align -Wmissing-prototypes -Wmissing-declarations
  184.   -Wstrict-prototypes -Wnested-externs".
  185.  
  186. - Om man skickar patchar s├Ñ ska man anv├ñnda "diff -u" (eller "diff -r
  187.   -u" eller "cvs diff -u"). Se
  188.   <http://www.freeciv.org/contribute.html> f├╢r ytterligare
  189.   upplysningar. Man ska ├ñven ge patcharna beskrivande namn (till
  190.   exempel "fix-foo-0.diff", men inte "freeciv.diff").
  191.  
  192. - N├ñr man k├╢r "diff" f├╢r en patch s├Ñ ska man se till att utesluta
  193.   on├╢diga filer genom att anv├ñnda kommandoradsargumentet "-X" f├╢r
  194.   programmet "diff":
  195.  
  196.     % diff -ruN -Xdiff_ignore freeciv_c freeciv > /tmp/fix-foo-0.diff
  197.  
  198.   En f├╢reslagen "diff_ignore"-fil f├╢ljer med Freeciv.
  199.  
  200. ===========================================================================
  201.