doc/www/codingguide.php

   1 <? include ("barry.inc"); ?>
   2
   3 <? createHeader("Coding Guidelines"); ?>
   4
   5 <? createSubHeader("Style Guide"); ?>
   6
   7 <p>I use plain old vim for editing files.  As such, tabs are standard 8
   8 spaces wide.  When aligning the code, indents are always tabs.
   9 <pre>
  10         if( something ) {
  11                 // tab to indent
  12         }
  13 </pre>
  14 </p>
  15
  16 <p>Sometimes I need spaces to align function call parameters:
  17 <pre>
  18         void ClassName::Function(int lots,
  19                                  int of,
  20                                  int parameters,
  21                                  int that_need_spaces_and_tabs,
  22                                  int to_align_perfectly)
  23         {
  24                 // tab again
  25         }
  26 </pre></p>
  27
  28
  29 <p>I even use tabs to align the beginning parts of comments:
  30 <pre>
  31         ///
  32         /// \file       tab_to_filename.cc
  33         ///             Tab to the doxygen description
  34         ///
  35 </pre></p>
  36
  37 <p>I also use tabs to align things like simple #define numbers:
  38 <pre>
  39         #define ASDF_NAME       0x01    // tab between name and number
  40         #define ASDF_BODY       0x02    // tab between number and comment
  41 </pre>
  42 </p>
  43
  44 <p>The main place where I <b>don't</b> use tabs is inside tables that have to
  45 be aligned, especially where there's not enough space to fit things in
  46 one line when using tabs.  For example, in the record classes, those
  47 FieldLink&lt;&gt; tables might use tabs for the initial indent,
  48 but <b>everything</b> else is spaces, to keep things lined up, and compact:
  49 <pre>
  50         FieldLink<Task> TaskFieldLinks[] = {
  51            { TSKFC_TITLE,      "Summary",     0, 0, &Task::Summary, 0, 0 },
  52            { TSKFC_NOTES,      "Notes",       0, 0, &Task::Notes, 0, 0 },
  53            { TSKFC_START_TIME, "Start Time",  0, 0, 0, 0, &Task::StartTime },
  54            { TSKFC_DUE_TIME,   "Due Time",    0, 0, 0, 0, &Task::DueTime },
  55            { TSKFC_ALARM_TIME, "Alarm Time",  0, 0, 0, 0, &Task::AlarmTime },
  56            { TSKFC_CATEGORIES, "Categories",  0, 0, &Task::Categories, 0, 0 },
  57            { TSKFC_END,        "End of List", 0, 0, 0, 0, 0 },
  58         };
  59 </pre></p>
  60
  61 <p>As for coding style, I keep opening braces on the statement line:
  62 <pre>
  63         for( ... ) {
  64         }
  65
  66         if( something ) {
  67         }
  68         else {
  69         }
  70 </pre></p>
  71
  72 <p>Except for switches, because that's just wrong. :-)
  73 <pre>
  74         switch( something )
  75         {
  76         case 1:
  77                 break;
  78         case 2:
  79                 break;
  80         default:
  81                 break;
  82         }
  83 </pre></p>
  84
  85 <p>I put spaces inside the parentheses too.</p>
  86
  87 <p>For reeeeeally long lines, I sometimes favour keeping it all on one line
  88 and things wrap.  This is flexible... whichever looks best.  But also
  89 remember that grep is broken by wrapped lines, so if you're writing
  90 code that could conceivably be grepped later, decide whether breaking
  91 the line is worth it.  I usually try to keep error message strings on
  92 one line, even if they are long, since it makes it easier to grep for
  93 them when bug reports come in.
  94 <pre>
  95         // example error message....
  96         dout("Error 1234: too many rules");
  97 </pre></p>
  98
  99 <p>For pointer and reference variables, the pointer and reference symbol
 100 goes next to the variable, not the the type:
 101
 102 <pre>
 103         Data* data;           // wrong
 104
 105         Data *data;           // right
 106 </pre>
 107
 108 The reason for this becomes obvious when you consider what a multi-variable
 109 declaration looks like.  The first style confuses things.  The second
 110 flows naturally:
 111
 112 <pre>
 113         Data* block1, block2;  // wrong, declares a pointer and an object
 114
 115         Data *block1, *block2; // right, declares two pointers
 116 </pre>
 117
 118 <p>I think that covers it.  You may see some funky for() statements sometimes,
 119 due to size:
 120 <pre>
 121         for(    FieldLink&lt;Task&gt; *b = TaskFieldLinks;
 122                 b->type != TSKFC_END;
 123                 b++ )
 124         {
 125         }
 126 </pre></p>
 127
 128 <p>As long as it is clear to read, I'm generally ok.  You'll notice the
 129 fixation on tabs again in this example.  I'm less fussy about that,
 130 if it's clear to read.
 131 </p>
 132
 133 <p>Sometimes spaces are used to align ostream output as well:
 134 <pre>
 135         os &lt;&lt; "something"
 136            &lt;&lt; "something more"
 137            &lt;&lt; std::hex &lt;&lt; some_number;
 138 </pre></p>
 139
 140 <p>Chris Frey</p>
 141