Hi all,

since I don't like spending a sunny weekend in fruitless hidden discussions 
about "refactoring is bad if it reformats code" I've put up some thoughts 
about a possible style guide for Flightgear:

CODING POLICY:
==============

File Naming
-----------------
All filenames are all lower case. Header files end with the suffix .hxx, code 
files get the prefix .cxx. (Preferably?) The filename is just the class name 
that is defined therein, accordingly suffixed. (Preferably) Only one class is 
defined per file.

Rationale:
Having only one class per file and filenames according to the classes allows 
to find the files containing the declaration for a specific class more 
easily.

NOTE: In C++ lowercased filenames probably are a matter of taste, explained 
probably due to my Python background. In Python there exists no 
discrimination between modules and namespaces, so this rule is useful to 
distinguish between classes and modules/packages.

Class names
------------------
Class names generally are nouns that communicate the function of the class. No 
prefixes are used. Class names begin with an uppercase letter.

NOTE: Currently there are a lot of prefixes like FG... I don't see the need 
for them as that's what namespaces are for.

Function naming
-----------------------
Function names begin with a lowercase verb expressing clearly what the 
function does, probably followed by further specifications.

i.e.  readFlightplan(), extendGear()

Exception are methods that return a single 'property' (getters, calculation 
methods) or query methods that have a bool return value. Even then the method 
name starts with a lowercase letter though.

i.e. altitude(), leadpointReached()

Set methods always use the verb 'set'

i.e. setAltitude()

Rationale:
The lowercase letter helps to distinguish functions and methods from class 
constructors. An good self sufficient function name helps to write 'talking' 
code.

Not using the 'get' prefix is not only shorter but also helps to write more 
appealing 'readable' code, as in 

if (altitude() == targetAltitude())...

vs.

if (getAltitude() ==getTargetAltitude())....

The fact that altitude is a getter is simply concluded from the fact, that it 
is a function but doesn't start nor ends with a verb. (targetAltitude is a 
bad example here ;-) )

Using a different rule for bool returning query methods stems from the fact 
that the code is more readable in the places the function is used, as putting 
the verb at the end is more natural in questions.

NOTE: I favour camel case but thats completely open for discussion as its more 
or less a pure matter of taste. An alternative are underscores and all 
lowercase, i.e. read_flightplan(), extend_gear()

Variables
-------------
The names of private attributes of a class begin with an underscore followed 
by a lowercase letter, i.e.  _pitch, _altitude

Rationale:
If applied consistently for only this purpose, the underscore instantly 
communicates the variable at hand as being private to the class.

NOTE: One alternative is to prefix with 'm' , i.e. mPitch or m_pitch. IMO the 
first case is less readable, whereas in the second case the m is obsolete as 
the underscore suffices.

Braces
----------
Opening braces are on the same line as the preceding statement (function 
declaration, if clause, etc.). Closing braces follow a newline and are 
properly indented to align with the block they close.

Rationale:
Putting the opening brace that way saves an extra line of screen space. The 
block opening is well visually communicated by indenting the following code.
Putting the closing brace on a line on its own helps when scrolling down the 
code for the block end.

Indentation
---------------
The code uses 4 spaces for indentation.

Rationale:
As tab size is dependent on personal configuration and therefore 
unpredictable, only spaces are allowed to indent code blocks. 4 spaces is a 
compromise between readability and screen space used.

=================

I surely have forgotten a lot but at least thats a basis for open discussion.

Thomas
-- 
PhD Student, Dept. Animal Physiology, HU Berlin
Tel +49 30 2093 6173, Fax +49 30 2093 6375

-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
Flightgear-devel mailing list
Flightgear-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/flightgear-devel

Reply via email to