| 2 |
- |
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 (and this is not an exhaustive list):
|
|
|
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.
|