Re: Debian coding style?
>
> Query, is there actually a coding style guideline for debian stuph?
>
> Basically I'm with the Corel Linux group and this is what the Corel
> Linux Coding guidelines say... (follows). A few note-worthy ones are:
> - tabs: 2 spaces
> - curly braces alway on next line
> ie if (...)
> {
> }
> else
> {
> }
> - hungarian notation
>
> Will the Debian community be excrusiatingly unhappy with this?
I believe they will be.
I have seen many bad or ugly coding styles and a very few good ones.
One of the best I've ever seen is that used for Tcl/Tk C source code.
Please have a look at it. Tcl C code is well indented, easy to read
and uses reasonable conventions about variables functions names and
comments.
> 3. Tabs should be set to 2, and they should be kept as tabs, no spaces
> please.
Absolutely not. Almost all text processors have 8 spaces tabs. Any other
size means only a lot if troubles to all develpers, except those at Corel.
I usually use 4 space indentation with 8 spaces hard tabs.
> 4. Code width: The complete line of code should be visible without having to
> scroll horizontally - i.e. it should normally not pass the 78th column.
I agree, it makes code easier to read.
> 5. Naming conventions:
> ...
> Hungarian Notation:
> ...
Nobody except Micro$oft uses that. Again, compare a source file in Hungarian
notation with a Tcl C source file.
> * Magic numbers must not be embedded directly in the source code. Use a
> const int variable to hold the magic number rather than a #define.
I totally agree.
> 7. Comments : Please comment your code, it makes everyone's life easier.
> ...
I agree. Comments are as important as the code itself. Again, see Tcl style.
But please use /* */ instead of //. It is far easier to read.
> 10. Function/method size: bigger is not better. Functions and methods should
> be kept to a maximum of 40-50 lines. Larger methods should be broken down
> into several smaller methods.
This could be accepted as a guideline but not strictly enforced. Sometimes a
long function can be better, faster or easier to write than many small ones.
And if you have many while/if/else the effective code size could be not more
than 20-25 lines, excluding the curly braces...
> 11. Curly braces
>
> a) location must be on the next line and right underneath the 1st coding
> column of the line directly above it.
This is good for functions but a waste of space for if/for/while constructs.
Unfortunately not everyone can switch to a 1600x1200 monitor while coding.
> b) All statements following if, while, for, ... etc. must be enclosed within
> braces even if it is only 1 line.
I like this, but many peole don't agree. I would say 'should'.
> 12. Spacing
>
> a) there must be spaces separating each binary operator and each keyword.
> eg. a = b; and not a=b
I like also this.
> b) blank spaces should not be left between method/function names and the
> opening bracket.
I agree.
> c) blank spaces should not be left immediately after an opening bracket, nor
> immediately before a closing bracket
>
> eg. DoIt(this); and not DoIt( this );
>
> if (test) and not if ( test )
IMHO a waste of space in general. Useful only in some cases.
> e) multiple parameters to methods/functions should be separated by a comma
> followed by a single blank space (not a tab)
>
> eg. DoIt(this, that, theOther);
Ok.
> g) leave blank lines between sections of code. Each major section of code
> should include a comment explaining what it's purpose is.
I agree.
> 14. Compilation conditionals, with the exception of debug code noted above,
> should be avoided 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.
Compilation conditionals can't be avoided if you want your code to be
portable to multiple platforms. Old code should really be dropped.
> 16. Goto statements should not be used.
In generally they should not be used, except for jumping to exit code in
case of error. There may be other useful exceptions too.
> 17. Return: functions and methods should be structured to have a single
> return.
If you forbid jumps but want a single return you will end up writing very
contorted code. Both jumps and multiple returns can be good if used with
caution.
> 19. Comparisons for equality against a constant value should list the
> constant value first. Its easy to miss one of the equals signs - this way
> the compiler will catch it if you do.
>
> eg. if (-1 == m_nResult) rather than if (m_nResult == -1)
Reasonable from a software engineering point of view, but very unnatural
to read for humans. I prefer the contrary and let the compiler warn me in
case of suspicious statements. Let the computer do the job for you.
> 20. Header files must not include other header files (to prevent header file
> bloat). Use forward class references to inform compiler of required data
> types.
I don't agree. Header files should be enclosed inside a #ifdef to allow
multiple inclusions and include whatever they need or want to include.
> 21. Filenames: source files should have .cpp extension. Header files should
> have a .h extension. All filenames should be created using only lower case
> characters. All filenames in #include statements should also be written in
> lower case. Source and header files should normally reside in the same
> directory. Large projects should be split up into smaller sub-projects to
> keep the number of source files in each directory manageable.
Only M$ uses this extension. All the the other seem to use .cc.
Anyway I would suggest using plain C whenever possible. C++ is generally
good only to stress cpu and harddisks.
> 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.
This will maybe ease the pain of possible future translators but it will
surely increase the pain of developers. The best I18N tool is GNU gettext.
With it you don't even need to recompile or relink the programs.
And the practice of compiling translations in the executable, a typical
M$ bad practice, makes impossible to have multilingual version of the
applications on the same machine. I would also avoid the X/Opens catgets.
--
Massimo Dal Zotto
+----------------------------------------------------------------------+
| Massimo Dal Zotto email: dz@cs.unitn.it |
| Via Marconi, 141 phone: ++39-0461534251 |
| 38057 Pergine Valsugana (TN) www: http://www.cs.unitn.it/~dz/ |
| Italy pgp: finger dz@tango.cs.unitn.it |
+----------------------------------------------------------------------+
Reply to: