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
|
About This Directory
====================
This directory contains support files that I use for developing this
project. I recommend others consider doing the same.
Coding Style
~~~~~~~~~~~~~~~~~~~~~~~~~
I'm using Sublime Text as my development IDE, and so I've set things up
for that. But, I think you should be able to use any reasonable editor.
A clang-format configuration file is included in the project, you should
use that. (clang format requires that the style file live at the top of
of the project tree, not somewhere else, such as this etc directory.) The
format rules are probably inappropriate for the test/ subdirectory, as
the Convey framework has a style all it's own.
The style is based loosely on WebKit, but is really modified -- someday
if clang-format ever learns about BSD KNF I'll probably switch to that.
Once upon a time this used uncrustify. However, the frequent breaking changes
in uncrustify versions, and the fact that the latest (at this time 0.65) does
not actually support one of the most common language constructs (extern "C"
opening braces) has driven me towards clang-format. The good news is that
this is probably actually easier for most folks to use.
Sublime Text
~~~~~~~~~~~~
I've also arranged for Sublime text to understand that .h is C, not C++ (this
is important!)
ISO Standard C
~~~~~~~~~~~~~~
I've decided, after some gnashing of teeth, to finally accept that C99
is here to stay. Therefore, I'm *not* spending any effort into supporting
older C89/C90 compilers. That said I do understand that compiler support
for C99 is not always complete. I will stick to the mainstream features,
like <stdint.h>, the ability to use variadic macros, // comments, and perhaps
the occasional use of for() locally scoped variables.
We also insist that you have working vsnprintf, snprintf. Microsoft famously
did not, or worse, had broken ones (that didn't guarantee NULL termination).
Visual Studio 2015 reportedly fixes this. Building with older versions of
Visual Studio for Microsoft platforms may leave you with some brittle code
that could break in some bad ways -- use the latest to avoid this issue.
(I'm not aware of any other platform with this kind of brain damage.)
Naming Conventions
~~~~~~~~~~~~~~~~~~
Because not everyone wants to deal with CMake all the time, I anticipate that
there will be folks who in the future want to just create one monster .c
file that contains all these things, or even a .h that they just inline into
their programmer. As vile as this idea seems to me, I can understand the
motivations for it. In order to facilitate those cases, its important that
all global symbols use names prefixed with nni_ or nng_ (or NNI_ or NNG_ for
macro names). This is true even for static symbols that won't show up in
a more conventional symbol table.
We use nng_ (and NNG_) for symbols that are intended to be expoed to consumers.
These symbols form part of our public API.
We use nni_ and NNI_ for symbols that are *NOT* part of our public API and
should not be used by users.
Note that for the most part we try to avoid exposing structures directly to
users so that they don't get baked into binaries -- preferring instead to
dynamically allocate and give back an opaque pointer to the API. Any
exceptions to this case need to be VERY carefully reviewed to make sure
that the thing is unlikely to change (in any way whatsoever) in the future,
or that adequate provisions for versioning have been made.
|
