doc/www/codingguide.html

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