doc/CodingStyle.txt

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