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
|
Coding Guidelines for Gem
=========================
2011-2014, IOhannes m zmölnig
Questions
=========
Read the entire CodingStyle guide.
If you still have questions, please ask them on the gem-dev mailinglist:
http://lists.puredata.info/listinfo/gem-dev
A general discussion about the "contribution workflow" in Gem can be found in the gem wiki:
https://github.com/umlaeute/Gem/wiki/Contributing
Programming Language
====================
Gem is (mainly) written in C++.
C-style vs C++-style
--------------------
while Pd is written in C, Gem is written in C++;
please try to use C++ idioms whenever possible.
use STL instead of inventing your own data containers!
esp. use "std::string" instead of "char*" whenever possible
the Gem code base is full of C-idioms and types; this is mainly because i
started as a C-programmer and only gradually learned using C++; don't repeat my
follies :-)
C++ standard
------------
Gem compiles on many platforms: the build machine that builds the W32-binaries
is an old XP-machine running "Microsoft VisualStudio 6", which was released
in 1998. Gem needs to be able to compile on this machine.
This means, that we cannot use any new language features introduced after (or
around) that date, including: C++98, C++03, C++11, C++??
private/protected/public
------------------------
ctor/dtor should be public
methods should be protected/public
members should be protected
private members should be hidden using a PIMPL idiom
initialization
--------------
initialize all member variables in the constructor(s).
use "member initialization lists" when possible.
e.g. use
> foo::foo(void) : m_x(0), m_y(0) {}
rather than
> foo::foo(void) { m_x=0; m_y=0; }
callbacks
---------
message callbacks from the RTE should be implemented using the CPPEXTERN_MSG*
macros defined in src/RTE/MessageCallbacks.h
this removes the need for static callbacks in the header-files
variable naming
---------------
member variables should be prefixed with "m_"
static variables should be prefixed with "s_"
import/export
-------------
all functions/classes that should be visible from outside must be exported using
the GEM_EXTERN macro.
all objectclasses are exported.
all utility classes are exported.
Dependencies
============
the dependencies of Gem should be kept at a minimum (ideally only openGL)
objectclasses that use special libraries should go into extra/
if you want to add functionality to Gem that is (or can be) implemented by a
number of different backends (libraries), this should be done via an abstract
interface and *plugins*, thus moving the binary dependency outside of Gem.
Code layout
===========
whitespace
----------
Please avoid *any* trailing whitespace.
Remove trailing whitespaces before committing.
`git` has a *pre-commit* hook example, that checks for trailing whitespace and
will warn you when you try committing such code.
you can enable it with something like:
$ cp .git/hooks/pre-commit.sample .git/hooks/pre-commit
Indentation
-----------
It seems that the most common indentation in Gem's code base is:
- 2 spaces (yes, that's not much)
- no tabs (use spaces instead)
Bracing
-------
Try using the "One True Brace Style" (aka 1TBS, a variant of the K&R style)
http://en.wikipedia.org/wiki/Indent_style#Variant:_1TBS
Tools
-----
To re-indent a file you can use `astyle` tool with the options-file provided in `/doc/astyle.rc`.
(or simply run the script `build/tools/indent.sh` and pass the files to re-indent as arguments)
Filesystem layout
=================
directory structure
-------------------
src/Gem
Gem core architecture classes
src/Utils
Utilitiy code that can be re-used in several different contexts
src/RTE
Pd-specific code (RTE=Real Time Environment)
(in the far future i would like to have all Pd-specific code wrapped in
here)
src/plugins
plugin infrastructure and (pure virtual) baseclasses for the various
plugins
src/Base
Base classes for objectclasses
src/deprecated
deprecated headers for backward compatibility
src/Controls/
objectclasses: CONTROL
src/Manips/
objectclasses: MANIPulatorS
src/Geos/
objectclasses: GEometric ObjectS
src/Nongeos/
objectclasses: positionable Objects that are not Geos
src/openGL/
objectclasses: OPENGL wrapper objects
src/Particles/
objectclasses: PARTICLE engine
src/Pixes/
objectclasses: PIXEl proceSsing
src/Output/
objectclasses: window handling
plugins/*/
plugin implementations for various backends
extra/*/
additional objectclasses
directories containing objectclasses, should not hold auxiliary files!
these should go into src/Utils/ (if they are of general interest) or the code
should be embedded into the objectclass code.
a noteable exception is the extra/*/ folder
file structure
--------------
C++ files are suffixed ".cpp".
they are accompanied by a header file ".h" containing the public interface.
there is a file for each objectclass named like the objectclass. e.g.
> src/Manips/ortho.cpp
contains the code for the [ortho] objectclass.
|
