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
|
# Coding standards of `p4est`
This file describes a list of coding standards that the `p4est` software
library tries to adhere to.
## White space
`p4est` is a `C` library. We do not use `C++`-style comments `//`.
Please use `/* ... */` throughout.
All `.c` and `.h` files must be indented with the `p4estindent` script in
the main directory. It calls GNU `indent` with some extra options.
This does not apply to included third party code.
Different versions of `indent` produce different results. When in doubt,
please talk to us about various versions of `indent`.
An essential rule of thumb is to throw away white space changes to lines of
code not written by yourself.
Where `./p4estindent` goes bad, use `/* *INDENT-OFF* */` and `-ON` comments.
Use `doxygen` style for comments whenever possible. We're aiming at a
complete in-source documentation that runs through without warnings.
Comments and code should not exceed the 79th column.
## Portability
The code should be safe for C++ compilers. This means that all .h
files need to protect external declarations with `extern "C" { ... }`.
`C++` also needs explicit casts in many places where `C` does not care.
To test this, try
relative/path/to/configure --enable-mpi --enable-debug CC=mpicxx \
CFLAGS="-Wall -Wextra -Wno-unused-parameter -O0 -g"
and run `make -j V=0`. Modify accordingly for production builds.
## Boolean variables
All boolean parameters will not be checked with `(x==true)` or `(x==false)`.
We follow the standard `C` convention where `(x)` is used to test true
and `(!x)` is used to test false. The `bool` type is never used; use `int`.
An exception is to test explicitly for pointers being `NULL` or not,
like `(p == NULL)` or `(p != NULL)`.
## Integer types
For the indexing of trees use the `p4est_topidx_t` type.
For processor-local indexing use the `p4est_locidx_t` data type.
For globally unique indexing of potentially large numbers use the
`p4est_gloidx_t` data type. Quadrant and node coordinates are of type
`p4est_qcoord_t`.
The `int_8` data type may be used only to save storage space where it makes
a difference – this means usually not.
Generic integers and flags should be of `int` type.
Storage sizes should be `size_t`.
## Iteration variables
Loop variables of type `int` can be named as usual: `i`, `j`, etc.
Loop variables of type `size_t` should be named `iz`, `jz`, etc.
Loop variables of type `ssize_t` should be named `is`, `js`, etc.
Loop variables of type `p4est_topidx_t` should be named it, jt, etc.
Loop variables of type `p4est_locidx_t` should be named il, jl, etc.
Loop variables of type `p4est_gloidx_t` should be named ig, jg, etc.
There is usually no need to use any other type for loop counters.
## `printf` long integers
We will have to wait until all compilers and some lint checkers
understand
printf ("%jd %ju", (intmax_t) i, (uintmax_t) u);
since that would be a nice way to accomodate 128 bit integers without
changing the `printf` code.
This also holds for `size_t` since support for the following is still
incomplete:
printf ("%zd %zu", ssize_t_var, size_t_var);
In the meantime, we're using:
printf ("%lld %llu", (long long) verylongi, (unsigned long long) verylongu);
Checksums are formatted using `0x%08x` for `unsigned int` variables.
## Buffer sizes
We never use variable-length buffer output such as produced by `sprintf`.
What we do is calling safe versions like
char buf[BUFSIZ];
snprintf (buf, BUFSIZ, "Foo %d\n", bar);
|
