File: CODING-STANDARDS

package info (click to toggle)
gwyddion 2.57-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 48,860 kB
  • sloc: ansic: 405,916; python: 7,867; sh: 5,241; makefile: 4,507; xml: 3,786; cpp: 2,572; pascal: 418; perl: 154; ruby: 130
file content (340 lines) | stat: -rw-r--r-- 10,015 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340


===== 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 $