code_style.adoc revision 0bbfda8a 
1# Style Guidelines
2
3
4## Overall
5
6Most of these rules are meant to be general guidelines.  The overriding
7goal is for the code to _work_; if it doesn't do that, it's worthless.
8Given that it works, it should be _readable_.  These guidelines are aimed
9at achieving that goal; if you have to break a rule to be more readable,
10then do it.  If you have to bend a rule to match surrounding code, do it.
11
12ctwm is written in **C99**, to run in a generally **POSIX environment**,
13and is intimately related with **X11**.  Those worlds, in roughly that
14order, should be considered when making style choices.
15
16
17## Automatic
18
19http://astyle.sourceforge.net/[Artistic Style] is used to maintain
20gross code styling.  The `make indent` target will run it over the
21codebase, and should be used regularly to keep things in shape.
22
23These are thus hard rules; in theory, at any given time, running `make
24indent` should yield no changes.  This is the primary exception to the
25"`break the rules`" guideline above.  Code should always follow these
26rules, because it makes life simpler.
27
28
29## Include files and ordering
30
31* All source files should include `ctwm.h`, and always include it first.
32
33* Includes should be generally ordered as:
34
35** `ctwm.h`
36
37** (some vertical whitespace separator)
38
39** System includes (`stdio.h`, `X11/foo.h`, etc)
40
41** (some vertical whitespace separator)
42
43** Other local includes
44
45** However some special cases exist where we have to pull system files
46after the locals; _e.g._, when something in one of our headers is needed
47to figure what else to `#include`.  That's fine.
48
49* Generally, local includes should avoid ``#include``ing system includes
50where possible, and avoid ``#include``ing other local includes where
51practical.  If the file itself needs something from another header file
52(_e.g._, a  prototype or var extern needs a type from elsewhere), it
53should `#include` that; if however some `.c` file that ``#include``s the
54`.h` needs something from another header, generally the `#include` should
55be put there.
56+
57Bear in mind that this is a *guideline*.  There are extant exceptions,
58and may be more over time.  Make it readable and maintainable.
59
60* Try to avoid including things already brought in elsewhere.  For
61instance, `ctwm.h` already includes our `types.h`, the system
62`stdbool.h`, and many of Xlib's includes, so no other file in our tree
63need `#include` them.
64
65
66## Standards and Types
67
68ctwm is written in C, and currently against the **C99** standard.  Types,
69headers, functions, types, etc. defined there are assumed available, and
70should be the initial goto choice for such.
71
72It is also written to run in a **POSIX** environment, using **X11**, so
73the headers, functions, and types related to them are also considered
74available, and should be used when appropriate.
75
76### Boolean
77
78The case of boolean types gives a useful example.  C99 defines the `bool`
79type for booleans, with the boolean values `true` and `false` (defined to
80be numerically `1` and `0`).  The type and constants should be used in
81code in ctwm itself needing boolean variables or values.
82
83Xlib defined a `Bool` type, and the boolean values `True` and `False`
84(which are also numerically `1` and `0`).  They should be used in
85interactions with Xlib.  There are also some odder fringe cases we might
86hit; libjpeg has a `boolean` type, and `TRUE`/`FALSE` values.  Xt
87("Intrinsics") has a `Boolean` type, with `TRUE`/`FALSE` values.  When
88dealing with an external lib, use its types and values.
89
90Because of C's conversion rules, assigning values from one type to the
91other, via boolean conditional expressions, or via literal or numeric
921/0, should always work as expected.  However, the type representations
93aren't the same, so e.g.  passing a `+bool *+` to a function expecting a
94`+Bool *+` will go *very badly*.
95
96
97## Comments
98
99There is no part of the codebase with too many comments.  I dream of the
100day when we'll have to edit that line; please help hasten it!
101
102C99 allows both `+/* enclosed */+` and `// to EOL` comment styles.  We
103generally lean toward `+/* enclosed */+`, but `// to EOL` are acceptable
104as well.  In particular comments at the end of the line (like
105documentation of structure elements) are excellent candidates for `//`
106comments, particularly when they would otherwise wrap.
107