Debian Codegraph @

style.txt

raw
1 This is a catalogue of coding conventions used in JOVE. It is
2 incomplete -- we only list ones that are surprising or needed to be
3 corrected in contributions. Much can be inferred by reading the code.
4 Consistency is valued.
5
6 Bugs in an editor are very bad. Top priority is given to correctness.
7 We try to code in a way that lets the compiler detect problems (lint).
8 One consequence is that we try to eliminate things that cause
9 warnings, even if they are correct. Misbehaving on bad input counts
10 as a bug -- buffer overruns are to be protected against.
11
12 Indentation is done by tabs. Since 8 columns per indentation level is
13 excessive, we recommend setting the "tab-width" variable to 4. You
14 are using JOVE to edit JOVE, right?
15
16 C allows you to increment or decrement a variable using ++ or --. If
17 the expression's value is not going to be used, we avoid these operators.
18 Instead of the statement
19 i++;
20 write
21 i += 1;
22 Jon felt strongly about this.
23
24 JOVE is intended to be highly portable. It supports many ancient
25 systems. We cannot assume anything beyond K&R C. We cannot assume
26 POSIX. Some features of each are valuable enough that we use
27 conditional compilation to let us exploit them.
28
29 Many odd parts of JOVE are scar tissue from portability battles. We
30 try to document these. Don't assume that odd code is pointless.
31
32 All functions (except ones with a variable number of arguments) are
33 defined in the old style; all other declarations include prototypes
34 using the proto and ptrproto macros.
35
36 All functions are declared before use. Remember that a definition is
37 a kind of declaration.
38
39 All extern functions that we define are also declared in a header.
40 There are no other declarations of this function. The header is
41 included in the file defining the function so that the compiler can
42 check that the two declarations are consistent.
43
44 Use "const" and "void" wherever appropriate.
45 Use "NULL" wherever appropriate.
46 Use '\0' as the NUL character (not 0).
47
48 We define and use "bool", "YES", and "NO".
49
50 In a switch statement, if a case is meant to fall through into
51 another, add the comment /*FALLTHROUGH*/. This tells the reader (and
52 a certain C compiler) that the lack of "break;" is intentional.
53
54 The comment /*NOTREACHED*/ specifies that control will not reach this
55 point.
56
57 JOVE tries to be small and simple, but not too simple. Historically,
58 it could run on a PDP-11 with only 64K of memory for code and 64K for
59 data. Simplicity means that it can be understood completely.
60
61 JOVE does not use stdio. Historically, stdio didn't provide
62 facilities that were worth the cost. This may no longer be the right
63 tradeoff, but changing would be disruptive.