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