This commit was generated by cvs2svn to compensate for changes in r1375,
[chise/xemacs-chise.git.1] / etc / CODING-STANDARDS
1                         XEMACS CODING STANDARDS
2                                    
3                                   by
4
5                                Ben Wing
6
7
8 Copyright (c) 1996 Ben Wing.
9
10
11 This file documents the coding standards used in the XEmacs source
12 code.  Note that XEmacs follows the GNU coding standards, which are
13 documented separately in ../man/standards.texi.  This file only
14 documents standards that are not included in that document; typically
15 this consists of standards that are specifically relevant to the
16 XEmacs code itself.
17
18 First, a recap of the GNU standards:
19
20 -- Put a space after every comma.
21 -- Put a space before the parenthesis that begins a function call,
22    macro call, function declaration or definition, or control
23    statement (if, while, switch, for). (DO NOT do this for macro
24    definitions; this is invalid preprocessor syntax.)
25 -- The brace that begins a control statement (if, while, for, switch,
26    do) or a function definition should go on a line by itself.
27 -- In function definitions, put the return type and all other
28    qualifiers on a line before the function name.  Thus, the function
29    name is always at the beginning of a line.
30 -- Indentation level is two spaces.  (However, the first and following
31    statements of a while/for/if/etc. block are indented four spaces
32    from the while/for/if keyword.  The opening and closing braces are
33    indented two spaces.)
34 -- Variable and function names should be all lowercase, with underscores
35    separating words, except for a prefixing tag, which may be in
36    uppercase.  Do not use the mixed-case convention (e.g.
37    SetVariableToValue ()) and *especially* do not use Microsoft
38    Hungarian notation (char **rgszRedundantTag).
39 -- preprocessor and enum constants should be all uppercase, and should
40    be prefixed with a tag that groups related constants together.
41
42
43 Now, the XEmacs coding standards:
44
45 **** Specially-prefixed functions/variables:
46
47 -- All global C variables whose value is constant and is a symbol begin
48    with a capital Q, e.g. Qkey_press_event. (The type will always be
49    Lisp_Object.)
50 -- All other global C variables whose value is a Lisp_Object (this
51    includes variables that forward into Lisp variables plus others like
52    Vselected_console) begin with a capital V.
53 -- No C variables whose value is other than a Lisp_Object should begin
54    with a capital V. (This includes C variables that forward into
55    integer or boolean Lisp variables.)
56 -- All global C variables whose value is a struct Lisp_Subr begin with a
57    capital S. (This only occurs in connection with DEFUN ()).
58 -- All C functions that are Lisp primitives begin with a capital F,
59    and no others should begin this way.
60
61 **** Functions for manipulating Lisp types:
62
63 -- Any function that creates an empty or mostly empty Lisp object
64    should begin allocate_(). (*Not* make_().) (Except, of course,
65    for Lisp primitives, which usually begin Fmake_()).
66 -- Any function that converts a pointer into an equivalent Lisp_Object
67    should begin make_().
68 -- Any function that converts a Lisp_Object into its equivalent pointer
69    and checks the type and validity of the object (e.g. making sure
70    it's not dead) should begin decode_().
71 -- Any function that looks up a Lisp object (e.g. buffer, face) given
72    a symbol or string should begin get_(). (Except, of course, for
73    Lisp primitives, which usually begin Fget_()).
74
75 **** Other:
76
77 -- Any header-file declarations of the sort
78
79    struct foobar;
80
81    go into the "types" section of lisp.h.