===== Identifiers ===================================================

General:
- The length of identifier name is roughly proportional to its scope
  and its role in the program.

  [Rationale:
  The more global is an identifier, the higher is the chance it's needed
  in different context and the chance of name clash.  So the name has
  to be more descriptive.  On the other hand, code readability is not
  improved by calling a temporary loop counter intTemporaryLoopCounter2
  instead of i, quite the contrary.]

- Global identifiers are compound of words tied with underscores, they
  are descriptive and unambiguous.  Local identifiers are short.  When
  there's no reason for doing otherwise, short (one-letter) identifiers
  correspond with types they are commonly used for:
  i, j, k, m, n - integer
  c - char
  s - string
  p - pointer
  r, t, w, x, y - floating point
  But this is in no sense strict.

- Hungarian notation is not used.

    extern int foo_bogosity_level;
    static int always_restore_state;

    int
    foo_get_bogosity_level(void)
    {
        int i;
        void *p;
        char c;
        char *s;
        ...
    }

    static void
    self_destruct(void)
    {
        ...
    }

Scope:
- Variables are declared in the scope where really used, to emphasize
  their scope (where it's unclear):

  int
  foo(int n, FooBar *ff)
  {
      int i;

      for (i = 0; i < n; i++) {
          const char *name = ff[i]->name;
          double q = ff[i]->quotient;
          ...
      }
      ...
  }


Types:
- Standalone structures, unions and enums are typedef-ed and type indentifiers
  are used:

  typedef struct {
      gint i;
      gint j;
  } CoupleOfInts;

  CoupleOfInts var;

  Bare struct foo, enum foo, etc. are not used.


Prefixes:
- No identifiers start with prefixes colliding with some standard or
  possibly used library.  Identifiers colliding with libc functions are
  avoided; common problematic identifiers include: y0, y1, yn, j0, j1,
  jn (math.h), index (string.h), exp2, log2 (math.h), fmax, fmin (math.h).

- All non-static identifiers use some unique prefix:
  Macros and constants: GWY_
  Types: Gwy
  Functions gwy_


===== Case ==========================================================

UPPERCASE_WITH_UNDERSCORES:
- enum constants:

    enum {
        FOO_NONE,
        FOO_SMALL,
        FOO_LARGE
    };

- Parameterless preprocessor macros:

    #define BOGUS_CONSTANT 4.2e1

- Other preprocessor macros if they are used like macros:

    #define ABS(x) ((x) < 0 ? (-(x)) : (x))

  Function wrappers look like functions:

    #define foo_bogo(one, two) bar_measure_bogosity(two, one, 0)

MixedCaseWithoutUnderscores:
- Compound types, enums, and structures:

    typedef struct {
        void *foo;
        int bar;
    } FooBar;

lowercase_with_underscores:
- Everything else (functions, variables, atomic types):

    int i;
    typedef unsigned char byte;

    int
    cup_of_tea(int flavor)
    {
        ...
    }


===== Indentaion and grouping =======================================

Indentation unit is 4 spaces.  Tabs are not used.  Empty lines are not
indented (and, generally, trailing spaces are avoided).

Functions:
- Function return type starts in the first column.
- Function name starts in the first column.
- Function opening brace starts in the first column:

    const FooBar*
    gimme_some_foobar(void)
    {
         ....
    }

Conditions, cycles, ... - code grouping:
- Opening brace (if present) ends the line before the group starts:
- Closing brace is alone on the line wehre group ends (except for
  do-while cycles):

    if (i == 0) {
        while (j > 0) {
            ...
        }
    }
    else {
        do {
            ...
        } while (j < 100);
    }

- Standalone groups start with an unindented opening brace:

    {
        int t1, t2;
        Foo *f = foobar[3].ff;
        ...
    }

- Multiline statements are grouped even if not necessary:

    if (foo) {
        for (i = 0; i < n; i++)
            sum += z[i];
    }

- else-if is not progressively indented:

    if (foo == 2)
        bar();
    else if (foo > 4)
        baz();
    else
        abort();

- case is not progressively indented:

    switch (c) {
        case 'a':
        croak();
        break;

        case 'm':
        carp();
        break;

        ...
    }

- Vim settings

  set shiftwidth=4
  set cindent
  set cinoptions=>1s,e0,n0,f0,{0,}0,^0,:1s,=0,g1s,h0,t0,c3,C1,(0,u0,)40,*60

===== Spaces =========================================================

Spacing emphasizes priority and thightness of binding.  The more
logically related are things, the less is the probability of a space
between them.

Horizontal spaces:
- There is always a space:
  after comma
  around ? and : in conditional expression
  around comparsion operators (==, <, >, <=, >=, !=)
  around assignment operators (=, +=, -=, ...)
  around binary logical operators (||, &&)

- There is never a space:
  around relationship operators (., ->, ::, .*, ->*)
  before function call and indexing operators ((), [])
  after reference or dereference operator (&, *)
  after negation operators (-, ~, !)
  before post-increment and post-decrement operators (++, --)
  after pre-increment and pre-decrement operators (++, --)
  after type cast ((int*))

- Spacing of other operators is choosen to emphasize priority:

    z = x + 3*y;
    q = a<<4 + b;
    c = m+n | 0xff;

- There is a space before if, while, or switch opening parenthesis.

    while (p != NULL)
         ...

- There is no space before function call (or macro) opening parenthesis.

    foo(bar(x), baz(y));

Empty lines:
- There's always an empty line after declarations in a group.
- There's always at least one empty line between functions, structs and
  and other compound definitions (declarations).
- There's always an empty line after while line in do-while cycles, except
  when a closing brace follows.

===== Miscellaneous ==================================================

There are no extra parentheses around return values in return statements:

  return x + y;

or case values in switch statements:

  case GTK_FOOBAR:

===== Documentation ==================================================

Each public function implementation is preceeded with a comment consisting
of its documentation in gtk-doc format.  This is also the prefered format
of private function documentation when a longer description is needed.

Other public symbols (types, macros, constants) that have no implementation
are documented at the end of a source file corresponding to the header file
they are declared in.

References to other symbols:
- Functions and function-like macros are written with () after their name
  so that gtk-doc turns them into hyperlinks: some_function().
- Type (struct, enum, object) names are written with # before name so that
  gtk-doc turns them into hyperlinks: #GwyContainer, #GwyInterpolationType.
- Constants and parameterless macros are written with % before name so that
  gtk-doc turns them into hyperlinks: %TRUE, %FALSE.
- Argument names are written with @ before name: @src, @dest, @n_of_gnats.

Body:
- Function documentation starts with a short (usually one-line) summary of
  its purpose.  It is written in third person, i.e. `Does something', not
  `Do something'.  For simple functions this summary is sufficient.
- The rest of documentation follows as separate paragraph[s], describing
  details, side-effects, warnings, usage examples, etc.

Arguments:
- Argument descriptions are sentences (even if incomplete), so start with
  a capital and end with a full stop.
- Objects in the role of `self' are usually described as `A something'.
- Argument names themselves are self-documenting, it is an error to name
  arguments `a' and `b' when they represent source and destination.  Names
  in documentation must match _header_ file for gtk-doc processing (ideally,
  argument names in implementation are identical too).
- Input parameters are normally constant; if a function can change them or
  takes their ownership, this fact is explicitely mentioned even if it's
  deducible from function signature.  (An exception are `self'-like object
  arguments whose modification is clear from function purpose.)
- Argument description contains not only parameter meaning, but also its
  interpretation if it is necessary to supply meaningful values without
  looking at function source code, e.g.:
  - if the argument is an angle, its description mentions whether in radians
    or degrees, and if it's measured clockwise or counterclockwise, and from
    what,
  - if the argument is a color [component], its description mentions the range
    representing [black,white], it may be [0,1], [0,255], [0,65535], etc.,
  - if the argument is other ranged value or dimensionless parameter, the
    range of valid or reasonable values is specified,
  - if the argument could be either physical or pixel dimension based quantity,
    its nature is specified,
  - if the argument is a boolean, its description explicitely mentions what
    %TRUE and %FALSE mean (or at least one of them), instead of just
    `switch nonfoo on/off'.
- Argument description also lists special values that can be passed, like -1
  for default, unspecified value.

Return value:
- Eventual return value is described in a Returns block after description
  body.
- Returns value has no default const/newly allocated convention, description
  of nonatomic values thus always specifies whether it's newly allocated, or
  should be treated as constant, and eventual ownership and lifetime rules
  (i.e., if return value is a static buffer that can be changed by another
  call, this must be mentioned).
- The item about argument interpretation applies to return value too.

Since:
- Each symbol lists Gwyddion version it was introduced in a line in form
  Since: 1.6
  as the very last paragraph of its documentation.



# $Id: CODING-STANDARDS 20683 2017-12-18 18:43:21Z yeti-dn $