Re: Debian coding style?
I say that the coding style ought to be as follows:
* Everyone ought to write code such that indentation and placement of
block elements on code are such that the ability of others to read
the code is maximized.
Additionally, I should mention that the below guidelines are very
C++-centric; better guidelines will apply to any language that has
similar syntax. Again, better to go up to the concepts that cover
these then drilling down to the specific implementation.
uwd38znr@umail.furryterror.org (Amy Fong) writes:
> Linux Coding guidelines say... (follows). A few note-worthy ones are:
> - tabs: 2 spaces
This is very nasty. Tabs are defined as occuring at every 8th
character; they are not a fixed width, and not every two spaces.
> - curly braces alway on next line
> ie if (...)
> {
> }
> else
> {
> }
I have no problems reading code like that but I prefer to not write it
such. Cf "bsd" mode in xemacs.
> - hungarian notation
Aiee! That's scary. :-)
> * Compiling: all code must compile clean at warning level 3 with warnings
> as errors.
Probably you mean -Wall -Werror here.
> 3. Tabs should be set to 2, and they should be kept as tabs, no spaces
> please.
This only compounds the error set above.
> 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.
Good one.
> 5. Naming 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.
I think that this is a bit overboard on the control side, and leads to
the Java-esqe problem of spending all one's time typing long names and
no time coding :-)
> c) Variable names must use hungarian notation (see below) followed by
I think that the whole premise behind Hungarian notiation is faulty.
That is, Hungarian notation is only used to clarify differences
between types of variables. This indicates that the programmer is
probably not using consistent variable types, which is bad anyway, and
moreover, are writing functions of such a length that they can't
remember the types of variables used. Both are bad.
In other words, Hungarian treats a symptom, not the problem.
> * 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.
There are certain cases in which it is desirable to use a macro
instead; most frequently, one might find this with doing bitwise
arithmetic.
> 7. Comments : Please comment your code, it makes everyone's life easier.
Certainly.
> 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.
Agreed on priciples, but there are cases in which exceptions are
desirable and cood.
> 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.
Many times, compilation conditionals are the only way to make
something compile on the dozens of platforms that we work with today.
> 16. Goto statements should not be used.
Bad idea. Yes I know what people say, but there *are* times when
gotos and far jumps can be good. While not strictly necessary, they
can help.
> 17. Return: functions and methods should be structured to have a single
> return.
This is also not a good idea. I often find myself checking input and
returning from the function early if it's not what I want to deal
with.
> 18. Switch statements must always handle the default: case. If all expected
> cases have otherwise been handled, the default: case should force an
> assertion failure. Case statements should be indented by 1 tab and separated
> from each other by 1 blank line. Code within each case should be kept to a
> minimum - i.e. call a function from the case statement if more than a few
> lines of code are needed.
There is not always a special "default" case. (ie, enums) While
strictly it is there, the compiler will give you a warning if you
don't handle every option anyway.
> 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.
Header files including others are often great ways to simplify the
code and make it easier to read.
> 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.
Well, if you're going to be doing localization, why not start with
gettext() from the beginning?
--
John Goerzen Linux, Unix consulting & programming jgoerzen@complete.org |
Developer, Debian GNU/Linux (Free powerful OS upgrade) www.debian.org |
----------------------------------------------------------------------------+
The 136,513,705th prime number is 2,827,044,919.
Reply to: