sys/man/6/style

   1 .TH STYLE 6
   2 .SH NAME
   3 style \- Plan 9 coding conventions for C
   4 .SH DESCRIPTION
   5 Plan 9 C code has its own conventions.
   6 You would do well to follow them.
   7 Here are a few:
   8 .IP • 3
   9 don't use
  10 .L //
  11 comments; some old Plan 9 code does, but we're converting it as we touch it.
  12 We do sometimes use
  13 .L //
  14 to comment-out a few lines of code.
  15 .IP •
  16 avoid
  17 .BR goto s.
  18 .IP •
  19 no tabs expanded to spaces.
  20 .IP •
  21 surround a binary operator (particular a low precedence one) with spaces;
  22 don't try to write the most compact code possible
  23 but rather the most readable.
  24 .IP •
  25 parenthesize expressions involving arithmetic and bit-wise operators;
  26 otherwise don't parenthesize heavily (e.g., as in Pascal).
  27 .IP •
  28 no white space before opening braces.
  29 .IP •
  30 no white space after the keywords
  31 .LR if ,
  32 .LR for ,
  33 .LR while ,
  34 etc.
  35 .IP •
  36 no braces around single-line blocks (e.g.,
  37 .LR if ,
  38 .LR for ,
  39 and
  40 .L while
  41 bodies).
  42 .IP •
  43 integer-valued functions return -1 on error, 0 or positive on success.
  44 .IP •
  45 functions that return errors should set
  46 .IR errstr (2).
  47 .IP •
  48 variable and function names are all lowercase, with no underscores.
  49 .IP •
  50 .B enum
  51 or
  52 .BR #define d
  53 constants should be Uppercase (or UPPERCASE).
  54 .IP •
  55 .B struct
  56 tags are Uppercase, with matching
  57 .BR typedef s.
  58 .IP •
  59 automatic variables (local variables inside a function) are
  60 never initialized at declaration.
  61 .IP •
  62 follow the standard idioms: use
  63 .L "x < 0"
  64 not
  65 .LR "0 > x" ,
  66 etc.
  67 .IP •
  68 don't write
  69 .L !strcmp
  70 (nor
  71 .LR !memcmp ,
  72 etc.)
  73 nor
  74 .LR "if(memcmp(a, b, c))" ;
  75 always explicitly compare the result of string or memory
  76 comparison with zero using a relational operator.
  77 .PP
  78 Ultimately, the goal is to write code that fits in with the other code
  79 around it and the system as a whole.  If the file you are editing
  80 already deviates from these guidelines, do what it does.  After you
  81 edit a file, a reader should not be able to tell just from coding
  82 style which parts you worked on.
  83 .SS COMMENTS
  84 If your code is readable, you shouldn't need many comments.  A line or
  85 two comment above a function explaining what it does is always welcome.
  86 .PP
  87 Comment any code you find yourself wondering about for more than 2
  88 seconds, even if it's to say that you don't understand what's going
  89 on.  Explain why.
  90 .PP
  91 Don't use commenting as an excuse for writing confusing code.  Rewrite
  92 the code to make it clear.
  93 .SS EFFICIENCY
  94 Do the simple thing.  Don't optimize unless you've measured the code
  95 and it is too slow.  Fix the data structures and the algorithms
  96 instead of going for little 5% tunings.
  97 .SH SEE ALSO
  98 ``Notes on Programming in C'', Rob Pike,
  99 .br
 100 .B http://www.literateprogramming.com/pikestyle.pdf
 101 .SH BUGS
 102 Some programs use very different styles, for example,
 103 .IR rc .
 104 .PP
 105 Some programs and programmers diverge from the above rules due to
 106 habits formed long before these rules.
 107 Notably, some programs have a single space after a keyword and
 108 before an opening brace,
 109 and some initialize automatic variables at declaration.