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.