Docs/CodingStyle

   1
   2                 Gnokii coding style
   3
   4                 (derived from Linux kernel coding style)
   5
   6 First off, I'd suggest printing out a copy of the GNU coding standards,
   7 and NOT read it.  Burn them, it's a great symbolic gesture.
   8
   9 Anyway, here goes:
  10
  11
  12                 Chapter 1: Indentation
  13
  14 Tabs are 8 characters, and thus indentations are also 8 characters.
  15 There are heretic movements that try to make indentations 4 (or even 2!)
  16 characters deep, and that is akin to trying to define the value of PI to
  17 be 3.
  18
  19 Rationale: The whole idea behind indentation is to clearly define where
  20 a block of control starts and ends.  Especially when you've been looking
  21 at your screen for 20 straight hours, you'll find it a lot easier to see
  22 how the indentation works if you have large indentations.
  23
  24 Now, some people will claim that having 8-character indentations makes
  25 the code move too far to the right, and makes it hard to read on a
  26 80-character terminal screen.  The answer to that is that if you need
  27 more than 3 levels of indentation, you're screwed anyway, and should fix
  28 your program.
  29
  30 In short, 8-char indents make things easier to read, and have the added
  31 benefit of warning you when you're nesting your functions too deep.
  32 Heed that warning.
  33
  34
  35                 Chapter 2: Placing Braces
  36
  37 The other issue that always comes up in C styling is the placement of
  38 braces.  Unlike the indent size, there are few technical reasons to
  39 choose one placement strategy over the other, but the preferred way, as
  40 shown to us by the prophets Kernighan and Ritchie, is to put the opening
  41 brace last on the line, and put the closing brace first, thusly:
  42
  43         if (x is true) {
  44                 we do y
  45         }
  46
  47 However, there is one special case, namely functions: they have the
  48 opening brace at the beginning of the next line, thus:
  49
  50         int function(int x)
  51         {
  52                 body of function
  53         }
  54
  55 Heretic people all over the world have claimed that this inconsistency
  56 is ...  well ...  inconsistent, but all right-thinking people know that
  57 (a) K&R are _right_ and (b) K&R are right.  Besides, functions are
  58 special anyway (you can't nest them in C).
  59
  60 Note that the closing brace is empty on a line of its own, _except_ in
  61 the cases where it is followed by a continuation of the same statement,
  62 ie a "while" in a do-statement or an "else" in an if-statement, like
  63 this:
  64
  65         do {
  66                 body of do-loop
  67         } while (condition);
  68
  69 and
  70
  71         if (x == y) {
  72                 ..
  73         } else if (x > y) {
  74                 ...
  75         } else {
  76                 ....
  77         }
  78
  79 Rationale: K&R.
  80
  81 Also, note that this brace-placement also minimizes the number of empty
  82 (or almost empty) lines, without any loss of readability.  Thus, as the
  83 supply of new-lines on your screen is not a renewable resource (think
  84 25-line terminal screens here), you have more empty lines to put
  85 comments on.
  86
  87
  88                 Chapter 3: Naming
  89
  90 C is a Spartan language, and so should your naming be.  Unlike Modula-2
  91 and Pascal programmers, C programmers do not use cute names like
  92 ThisVariableIsATemporaryCounter.  A C programmer would call that
  93 variable "tmp", which is much easier to write, and not the least more
  94 difficult to understand.
  95
  96 HOWEVER, while mixed-case names are frowned upon, descriptive names for
  97 global variables are a must.  To call a global function "foo" is a
  98 shooting offense.
  99
 100 GLOBAL variables (to be used only if you _really_ need them) need to
 101 have descriptive names, as do global functions.  If you have a function
 102 that counts the number of active users, you should call that
 103 "count_active_users()" or similar, you should _not_ call it "cntusr()".
 104
 105 Encoding the type of a function into the name (so-called Hungarian
 106 notation) is brain damaged - the compiler knows the types anyway and can
 107 check those, and it only confuses the programmer.  No wonder MicroSoft
 108 makes buggy programs.
 109
 110 LOCAL variable names should be short, and to the point.  If you have
 111 some random integer loop counter, it should probably be called "i".
 112 Calling it "loop_counter" is non-productive, if there is no chance of it
 113 being mis-understood.  Similarly, "tmp" can be just about any type of
 114 variable that is used to hold a temporary value.
 115
 116 If you are afraid to mix up your local variable names, you have another
 117 problem, which is called the function-growth-hormone-imbalance syndrome.
 118 See next chapter.
 119
 120
 121                 Chapter 4: Functions
 122
 123 Functions should be short and sweet, and do just one thing.  They should
 124 fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
 125 as we all know), and do one thing and do that well.
 126
 127 The maximum length of a function is inversely proportional to the
 128 complexity and indentation level of that function.  So, if you have a
 129 conceptually simple function that is just one long (but simple)
 130 case-statement, where you have to do lots of small things for a lot of
 131 different cases, it's OK to have a longer function.
 132
 133 However, if you have a complex function, and you suspect that a
 134 less-than-gifted first-year high-school student might not even
 135 understand what the function is all about, you should adhere to the
 136 maximum limits all the more closely.  Use helper functions with
 137 descriptive names (you can ask the compiler to in-line them if you think
 138 it's performance-critical, and it will probably do a better job of it
 139 that you would have done).
 140
 141 Another measure of the function is the number of local variables.  They
 142 shouldn't exceed 5-10, or you're doing something wrong.  Re-think the
 143 function, and split it into smaller pieces.  A human brain can
 144 generally easily keep track of about 7 different things, anything more
 145 and it gets confused.  You know you're brilliant, but maybe you'd like
 146 to understand what you did 2 weeks from now.
 147
 148
 149                 Chapter 5: Commenting
 150
 151 Comments are good, but there is also a danger of over-commenting.  NEVER
 152 try to explain HOW your code works in a comment: it's much better to
 153 write the code so that the _working_ is obvious, and it's a waste of
 154 time to explain badly written code.
 155
 156 Generally, you want your comments to tell WHAT your code does, not HOW.
 157 Also, try to avoid putting comments inside a function body: if the
 158 function is so complex that you need to separately comment parts of it,
 159 you should probably go back to chapter 4 for a while.  You can make
 160 small comments to note or warn about something particularly clever (or
 161 ugly), but try to avoid excess.  Instead, put the comments at the head
 162 of the function, telling people what it does, and possibly WHY it does
 163 it.
 164
 165
 166                 Chapter 6: You've made a mess of it
 167
 168 That's OK, we all do.  You've probably been told by your long-time Unix
 169 user helper that "GNU emacs" automatically formats the C sources for
 170 you, and you've noticed that yes, it does do that, but the defaults it
 171 uses are less than desirable (in fact, they are worse than random
 172 typing - a infinite number of monkeys typing into GNU emacs would never
 173 make a good program).
 174
 175 So, you can either get rid of GNU emacs, or change it to use saner
 176 values.  To do the latter, you can stick the following in your .emacs file:
 177
 178 (defun linux-c-mode ()
 179   "C mode with adjusted defaults for use with the Linux kernel."
 180   (interactive)
 181   (c-mode)
 182   (c-set-style "K&R")
 183   (setq c-basic-offset 8))
 184
 185 This will define the M-x linux-c-mode command.  When hacking on a
 186 module, if you put the string -*- linux-c -*- somewhere on the first
 187 two lines, this mode will be automatically invoked. Also, you may want
 188 to add
 189
 190 (setq auto-mode-alist (cons '("/usr/src/linux.*/.*\\.[ch]$" . linux-c-mode)
 191                        auto-mode-alist))
 192
 193 to your .emacs file if you want to have linux-c-mode switched on
 194 automagically when you edit source files under /usr/src/linux.
 195
 196 But even if you fail in getting emacs to do sane formatting, not
 197 everything is lost: use "indent".
 198
 199 Now, again, GNU indent has the same brain dead settings that GNU emacs
 200 has, which is why you need to give it a few command line options.
 201 However, that's not too bad, because even the makers of GNU indent
 202 recognize the authority of K&R (the GNU people aren't evil, they are
 203 just severely misguided in this matter), so you just give indent the
 204 options "-kr -i8" (stands for "K&R, 8 character indents").
 205
 206 "indent" has a lot of options, and especially when it comes to comment
 207 re-formatting you may want to take a look at the manual page.  But
 208 remember: "indent" is not a fix for bad programming.
 209