Re: [Flightgear-devel] Coding Style (Discussion Proposal) (was crash in AI traffic)
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Thomas Förster wrote: Am Dienstag 03 Juli 2007 10:31 schrieb Martin Spott: Perhaps you recall this thread: C++ code beautifier / Codingstandardsproposal Seems to me that we are just revisiting these issues. I can't remember having read a proposal that found general consensus in the mentioned thread - so I consider the whole claim as void, I got no response to my draft proposal, which I read as nobody cares. So you possibly might safely ignore any complaints. Thomas I read it, and I wouldn't say that I don't care, but there are plenty of things about which I care more. I didn't write a critique because some parts are not part of an enforceable coding standard, some parts I agree with, other parts I disagree with... and I know that those who care more passionately than I would never allow the parts I disagree with :) 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. I agree that file names should follow class names, and strongly disagree that their case should be different from the class. The current code base is pretty random about this. 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. Pretty standard stuff. I strongly agree about namespaces. It's now 2007... I'm annoyed that my limited attempts to use namespaces were deleted from patches I submitted :) Really, the SG and FG all over the place are distractions. Function naming --- Function names begin with a lowercase verb expressing clearly what the function does, probably followed by further specifications. Can't argue with that :) 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. I personally hate underscores or any other indication that a variable is a private member, with the rationale that a cursory reading of a well-written class will quickly give you that information anyway, but I know that the guardians of coding taste disagree with me. 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. I mostly agree, except for function definitions. That is just not a very widespread style. 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. Agreed, and I don't have much sympathy for those who want to view the code with some other indentation. Anyway, if you're going to adopt a coding style, you might as well adopt one that is familiar to most practitioners of the language, as is the one described here. However, it's easy to overestimate the importance of a uniform coding style. Experienced developers must adapt to different styles in course of their work, and this is not difficult as long as individual files or modules are written in a good, consistent style. It is surely in terrible taste to start coding away in a file in a different one from the one that already exists there, even if the new style is the official one. Tim -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.7 (GNU/Linux) Comment: Using GnuPG with Fedora - http://enigmail.mozdev.org iD8DBQFGiiUFeDhWHdXrDRURAnhPAJ4xPD3g3MRM1SEGMQMX6UEbNYFUBACghCr9 i+xDg9HTnf0KzvKEmIBVJCU= =OE7n -END PGP SIGNATURE- - 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
Re: [Flightgear-devel] Coding Style (Discussion Proposal)
Repost of (relevant parts) of Tim Moore's original posting in another thread to keep things organized :-) With permission Please use this thread for coding style discussions. Thomas 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. I agree that file names should follow class names, and strongly disagree that their case should be different from the class. The current code base is pretty random about this. 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. Pretty standard stuff. I strongly agree about namespaces. It's now 2007... I'm annoyed that my limited attempts to use namespaces were deleted from patches I submitted :) Really, the SG and FG all over the place are distractions. Function naming --- Function names begin with a lowercase verb expressing clearly what the function does, probably followed by further specifications. Can't argue with that :) 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. I personally hate underscores or any other indication that a variable is a private member, with the rationale that a cursory reading of a well-written class will quickly give you that information anyway, but I know that the guardians of coding taste disagree with me. 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. I mostly agree, except for function definitions. That is just not a very widespread style. 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. Agreed, and I don't have much sympathy for those who want to view the code with some other indentation. Anyway, if you're going to adopt a coding style, you might as well adopt one that is familiar to most practitioners of the language, as is the one described here. However, it's easy to overestimate the importance of a uniform coding style. Experienced developers must adapt to different styles in course of their work, and this is not difficult as long as individual files or modules are written in a good, consistent style. It is surely in terrible taste to start coding away in a file in a different one from the one that already exists there, even if the new style is the official one. Tim - 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
Re: [Flightgear-devel] Coding Style (Discussion Proposal)
Am Dienstag 03 Juli 2007 13:54 schrieb Thomas Förster (actually it was Tim
Moore :-) ):
I personally hate underscores or any other indication that a variable is
a private member, with the rationale that a cursory reading of a
well-written class will quickly give you that information anyway, but I
know that the guardians of coding taste disagree with me.
This might work well with only private attributes. But then you get Java's
set/get hell. Combinations like setX(value) { _x = value;}; , x() { return
_x;}; are ridiculous. Why not just declare _x public. If later the need to
change attribute access arises, well then change it LATER. This ensures that
the author of the class at hand has to change all the now forbidden direct
accesses to the attribute. At least he is the one who best knows how to use
the class...
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.
I mostly agree, except for function definitions. That is just not a very
widespread style.
The rationale was to save the extra line imposed if the opening brace is on a
line of its own.
Also the 'rule' does not cover oneliners yet (i.e. inline/empty functions).
There all braces should be at the same line.
Anyway, if you're going to adopt a coding style, you might as well adopt
one that is familiar to most practitioners of the language, as is the
one described here. However, it's easy to overestimate the importance of
a uniform coding style.
I think there is lots of room in the continuum between 'nice to
follow'-guideline to mandatory-forced-rules.
Experienced developers must adapt to different
styles in course of their work, and this is not difficult as long as
individual files or modules are written in a good, consistent style.
Unfortunately consistent style is not always the case for FlightGear.
It is surely in terrible taste to start coding away in a file in a
different one from the one that already exists there, even if the new
style is the official one.
As is spending precious time to figure out an implicitly defined style. Which
will fail anyway for some obscure 'rules' overlooked ;-) I think
an 'official' style guide might help here as it should be OK to reformat the
whole file to the officially agreed style to ensure consistency. Maybe (to
relax it a bit to personal tastes) this could be done per subsystem or
module, though I'd prefer a single style for FlightGear as a whole.
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
[Flightgear-devel] Coding Style (Discussion Proposal)
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
