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.