[Opengc-devel] OpenGC style guide

[Damion S. <dam...@ho...>]

Hi all,

With the addition of many new coders recently I thought it might be a good
idea to go over a few programming style guidelines. Don't feel bad if you
haven't followed them up to this point, since I haven't bothered telling too
many people! After getting your feedback, I'll post a version on the
website. With large projects (which this is becoming) it's important for all
of the code in the project to look similar to avoid confusion by new people.

To clarify once again: this list is not a criticism of existing code! I've
sorted these by how flexible I think we should be in enforcing guidelines.

----Non-negotiable:

1) Set your editor to insert 2 spaces instead of tabs. With normal tabs,
indenting looks different depending on your editor setup. Spaces guarantee a
uniform appearance. I eventually hope to have a Perl script to check for
hard tabs and clean them up.

2) Insert a blank line at the end of each file to make GCC happy (otherwise
warnings result).

3) Member variables (public, protected, or otherwise) are named as
m_FooVariable. This allows you to rapidly distinguish between local function
variables and class members when reading class functions.
3a) Avoid underscore "_" characters in variable names. The exception to this
is the data source (as currently implemented).

4) Class member functions are named FunctionName. Bad names include:
functionName, functionname, Function_Name, etc.

5) Ifdef your header files. Don't use weird names (Visual Studio is good at
producing unusual ifdefs).

6) Include the copyright in front of each class you author. Be generous with
credit: if you base your code on someone else's, give them a contributor
credit.

----Somewhat negotiable:

1) Use white space liberally to improve readability.

2) Variable names should describe what they do. Good: m_DistanceToWaypoint,
Bad: m_Dw

3) The same goes for function names

----Very negotiable (i.e. up to personal taste but handy):

1) Name pointers as pFoo, and member pointers as m_pFoo.

2) Use doxygen style comments when possible. We don't currently use
doxygen - would it be useful to people?

3) Program in as generic a style as feasible. When possible, opt for several
classes with specific functionality rather than one mega-class.

---

Anyways, let me know what you think. Comments are encouraged.

Cheers,
-Damion-