doc/www/codingguide.php

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