10bbfda8aSnia# Style Guidelines 20bbfda8aSnia 30bbfda8aSnia 40bbfda8aSnia## Overall 50bbfda8aSnia 60bbfda8aSniaMost of these rules are meant to be general guidelines. The overriding 70bbfda8aSniagoal is for the code to _work_; if it doesn't do that, it's worthless. 80bbfda8aSniaGiven that it works, it should be _readable_. These guidelines are aimed 90bbfda8aSniaat achieving that goal; if you have to break a rule to be more readable, 100bbfda8aSniathen do it. If you have to bend a rule to match surrounding code, do it. 110bbfda8aSnia 120bbfda8aSniactwm is written in **C99**, to run in a generally **POSIX environment**, 130bbfda8aSniaand is intimately related with **X11**. Those worlds, in roughly that 140bbfda8aSniaorder, should be considered when making style choices. 150bbfda8aSnia 160bbfda8aSnia 170bbfda8aSnia## Automatic 180bbfda8aSnia 190bbfda8aSniahttp://astyle.sourceforge.net/[Artistic Style] is used to maintain 200bbfda8aSniagross code styling. The `make indent` target will run it over the 210bbfda8aSniacodebase, and should be used regularly to keep things in shape. 220bbfda8aSnia 230bbfda8aSniaThese are thus hard rules; in theory, at any given time, running `make 240bbfda8aSniaindent` should yield no changes. This is the primary exception to the 250bbfda8aSnia"`break the rules`" guideline above. Code should always follow these 260bbfda8aSniarules, because it makes life simpler. 270bbfda8aSnia 280bbfda8aSnia 290bbfda8aSnia## Include files and ordering 300bbfda8aSnia 310bbfda8aSnia* All source files should include `ctwm.h`, and always include it first. 320bbfda8aSnia 330bbfda8aSnia* Includes should be generally ordered as: 340bbfda8aSnia 350bbfda8aSnia** `ctwm.h` 360bbfda8aSnia 370bbfda8aSnia** (some vertical whitespace separator) 380bbfda8aSnia 390bbfda8aSnia** System includes (`stdio.h`, `X11/foo.h`, etc) 400bbfda8aSnia 410bbfda8aSnia** (some vertical whitespace separator) 420bbfda8aSnia 430bbfda8aSnia** Other local includes 440bbfda8aSnia 450bbfda8aSnia** However some special cases exist where we have to pull system files 460bbfda8aSniaafter the locals; _e.g._, when something in one of our headers is needed 470bbfda8aSniato figure what else to `#include`. That's fine. 480bbfda8aSnia 490bbfda8aSnia* Generally, local includes should avoid ``#include``ing system includes 500bbfda8aSniawhere possible, and avoid ``#include``ing other local includes where 510bbfda8aSniapractical. If the file itself needs something from another header file 520bbfda8aSnia(_e.g._, a prototype or var extern needs a type from elsewhere), it 530bbfda8aSniashould `#include` that; if however some `.c` file that ``#include``s the 540bbfda8aSnia`.h` needs something from another header, generally the `#include` should 550bbfda8aSniabe put there. 560bbfda8aSnia+ 570bbfda8aSniaBear in mind that this is a *guideline*. There are extant exceptions, 580bbfda8aSniaand may be more over time. Make it readable and maintainable. 590bbfda8aSnia 600bbfda8aSnia* Try to avoid including things already brought in elsewhere. For 610bbfda8aSniainstance, `ctwm.h` already includes our `types.h`, the system 620bbfda8aSnia`stdbool.h`, and many of Xlib's includes, so no other file in our tree 630bbfda8aSnianeed `#include` them. 640bbfda8aSnia 650bbfda8aSnia 660bbfda8aSnia## Standards and Types 670bbfda8aSnia 680bbfda8aSniactwm is written in C, and currently against the **C99** standard. Types, 690bbfda8aSniaheaders, functions, types, etc. defined there are assumed available, and 700bbfda8aSniashould be the initial goto choice for such. 710bbfda8aSnia 720bbfda8aSniaIt is also written to run in a **POSIX** environment, using **X11**, so 730bbfda8aSniathe headers, functions, and types related to them are also considered 740bbfda8aSniaavailable, and should be used when appropriate. 750bbfda8aSnia 760bbfda8aSnia### Boolean 770bbfda8aSnia 780bbfda8aSniaThe case of boolean types gives a useful example. C99 defines the `bool` 790bbfda8aSniatype for booleans, with the boolean values `true` and `false` (defined to 800bbfda8aSniabe numerically `1` and `0`). The type and constants should be used in 810bbfda8aSniacode in ctwm itself needing boolean variables or values. 820bbfda8aSnia 830bbfda8aSniaXlib defined a `Bool` type, and the boolean values `True` and `False` 840bbfda8aSnia(which are also numerically `1` and `0`). They should be used in 850bbfda8aSniainteractions with Xlib. There are also some odder fringe cases we might 860bbfda8aSniahit; libjpeg has a `boolean` type, and `TRUE`/`FALSE` values. Xt 870bbfda8aSnia("Intrinsics") has a `Boolean` type, with `TRUE`/`FALSE` values. When 880bbfda8aSniadealing with an external lib, use its types and values. 890bbfda8aSnia 900bbfda8aSniaBecause of C's conversion rules, assigning values from one type to the 910bbfda8aSniaother, via boolean conditional expressions, or via literal or numeric 920bbfda8aSnia1/0, should always work as expected. However, the type representations 930bbfda8aSniaaren't the same, so e.g. passing a `+bool *+` to a function expecting a 940bbfda8aSnia`+Bool *+` will go *very badly*. 950bbfda8aSnia 960bbfda8aSnia 970bbfda8aSnia## Comments 980bbfda8aSnia 990bbfda8aSniaThere is no part of the codebase with too many comments. I dream of the 1000bbfda8aSniaday when we'll have to edit that line; please help hasten it! 1010bbfda8aSnia 1020bbfda8aSniaC99 allows both `+/* enclosed */+` and `// to EOL` comment styles. We 1030bbfda8aSniagenerally lean toward `+/* enclosed */+`, but `// to EOL` are acceptable 1040bbfda8aSniaas well. In particular comments at the end of the line (like 1050bbfda8aSniadocumentation of structure elements) are excellent candidates for `//` 1060bbfda8aSniacomments, particularly when they would otherwise wrap. 107