Re: Debian coding style?
uwd38znr@umail.furryterror.org (Amy Fong) writes:
> Query, is there actually a coding style guideline for debian stuph?
The GNU project has coding guidelines, it might be worthwhile looking
into those.
http://www.gnu.org/prep/standards_toc.html
They are also available in some debian package, but I'm not sure which
one at the moment...
Debian is a collection of free software from all over the place. We
cannot (and probably would not if we could) enforce our personal
stylistic preferences on all free software developers everywhere.
As for indentation, brace alignment, and such, well, that's why I keep
a copy of indent(1) on my system. I think consistency within a
specific set of code is good (i.e. the source for package X), but
aside from that I have no real preferences.
> - hungarian notation
> Will the Debian community be excrusiatingly unhappy with this?
I don't know about the Debian community, but *I* certainly will be
extremely unhappy with this. Hungarian notation *removes* flexibility
from the code, breaks badly in the face of complex type systems such
as C++ offers, and provides little or no advantages if you have
adequate tools (ctags/etags, decent compiler warnings, proper
prototypes, etc.) I won't actually come to your house and kill you if
you use hungarian notation, but the thought will probably cross my
mind. :-)
> * Compiling: all code must compile clean at warning level 3 with warnings
> as errors.
I'm not sure what "warning level 3" is. If you substitute "-Wall",
then I strongly approve.
> 2. Testing: all code must be compilable, tested, and DIFF'ed before being
> checked into source safe.
I hope you mean CVS. :-) But yes.
> 3. Tabs should be set to 2, and they should be kept as tabs, no spaces
> please.
I prefer to set up CVS to run indent on the code before it is checked
in. This allows the programmer to use whatever style he/she feels
most comfortable with, while still maintaining a consistent style
across the code base. But in any case, I don't care about the
details, as long as the released code is consistent.
> 5. Naming conventions:
Again, consistency is the key. If I'm writing code that relies
heavily on one particular library, I try to follow the conventions of
that library. Otherwise, I try to remain consistent with the ISO
standard library's conventions.
> a) Class names always start with upper-case 'C', followed by an upper-case
> letter, followed by mixed upper/lower case and must always take the form of
> a descriptive noun.
Inconsistent with the ISO libraries. As are most of the other
mentioned naming conventions. I'd only accept such naming conventions
if there were a pressing reason to do so, i.e. I was making heavy use
of a library that already followed such conventions. Which, I
suppose, Corel probably is, so, whatever.... :-)
> 14. Compilation conditionals, with the exception of debug code noted
> above, should be avoided
Should be well-factored so as not to interfere with the flow of
reading the code. Note that Microsoft, whose hand I recognize in
these guidelines, is strongly opposed to portability in general,
especially to non-MS platforms.
> since they make the source code difficult to read and
> maintain. Old or unwanted code should be deleted from the source files prior
> to check-in. Source safes history feature can be used to retrieve an old
> version of the file if the old code is ever required again.
The assumption here is that only the latest MS platform is a valid
target. And only old, out-of-date Microsoft platforms are valid
alternatives. Microsoft doesn't write code to run on
SysV/BSD/Linux/Hurd/Plan9, and doesn't want you to do so. I'd look to
the GNU coding guidelines for help with this issue, rather than to
Microsoft.
> 21. Filenames: source files should have .cpp extension.
Um, that obviously only applies to C++ code. :-)
There is no universally accepted extension for C++ files. Some
systems will only recognize .C (case sensitive) or .cc, others will
only recognize .cpp. I find .C to be ambiguous, so I prefer .cc or
.cpp. G++ doesn't really care. But, as with so much else,
consistency is the real key.
> 22. Localization: text which will be visible to the user should never be
> embedded within the source code. All string literals should be placed in a
> separate header file to ease the pain of possible future translation.
See GNU gettext. (Which, I believe, can even be used on MS platforms.)
> 23. member variables: all member variables must be initialized by the class
> constructor.
Unless it's inappropriate to do so. This is an excellent guideline,
but a terrible rule. Failing to distinguish between guidelines and
rules is one of the most common errors of prescriptive lists like this.
> 24. delete operations should be followed by an immediate reassignment of the
> associated pointer with a NULL value
Bad rule, gives a false sense of confidence in non-NULL pointers.
Acceptable as a guideline *with* that warning.
> 25. References should be used as parameters/return types rather than
> pointers whenever a NULL value is not permitted.
And when using a language that supports it. :-)
My comments on all the other rules fall into one of two categories:
a) good rule, or b) doesn't matter as long as you're consistent.
However, I still strongly recommend looking into the GNU coding style
guide. GNU, unlike MS, supports multiple platforms. And there's
certainly far more code in Debian that follows the GNU guidelines than
there is that follows the MS guidelines. So the GNU guidelines are
better *if* you want to be more consistent with existing practice
within the Debian community, the Linux community, and the free
software community.
cheers
--
Chris Waters xtifr@dsp.net | I have a truly elegant proof of the
or xtifr@debian.org | above, but it is too long to fit into
http://www.dsp.net/xtifr | this .signature file.
Reply to: