Re: [Plplot-devel] [PATCH] Qt driver: fix coding style

[Andrew R. <and...@us...>]

Geoff, 

This sounds an eminently sensible set of coding guidelines and close to
what I would have suggested. I have only a couple of comments (see below).

In general I don't have really strong feelings about these things. I would
like consistency though. As long as we can easily configure emacs to "do 
the right thing" I personally would be happy.

Andrew

On Thu, Jun 25, 2009 at 10:44:09PM -0500, Geoffrey Furnish wrote:
> 
> I would recommend that we publish a plplot-style that works with CC mode in
> [X]Emacs. 
> 
> Then the question is how that style is selected.  There is some trick
> involving file-local Emacs variables, which we could look up.
> 
> An alternative that I have used for some years, is something I call
> "infer-style", which figures out which style to use for a file based on where
> it sits.  This way it makes it easy for me to work on multiple projects which
> use different styles, with no tweaking of my Emacs config, and no messy
> file-local variables in the files in all the projects.
> 
> If we get as far as adopting a specific style for PLplot, I would be happy to
> share my Elisp hooks and doohickies with others.
> 
> As for specific suggestions on the elements of style, just to get some
> specifics out for consideration, I suggest:
> 
> 1) No tabs.  Tabs are evil.  Spaces only.
> 2) 4 spaces per indent level
> 3) Liberal use of spaces:
> 
>     This:
> 
>         if ( a != 0 && ( b == 2 || c == 2 - x ) ) ...
> 
>     rather than:
> 
>         if(a!=0&&(b==2||c==2-x)) ...
> 

All agreed.

> 4) Braces:
> 
>         if ( condition )
>         {
>             ...
>         }
>         else
>         {
>             ...
>         }

I have a slight personal preference for:

        if ( condition ) {
            ...
        }
        else {
            ...
        }

but I'm happy to live with the consensus.

> 5) Focus on language rules rather than "code-nany" style rules.
>    For example, to me, this is okay:
> 
>         if ( condition )
>             single_line_action();
> 
>         else
>             ...
> 
> The part between the if and the else does not require enclosure in braces,
> even though GCC 4.4 now whines about that in -Wall mode.

> 6) Somewhat controversial, but I actually do think warning free code is, to
>    an extent, a matter of style.  If we would agree to seek the elimination
> of all warnings from GCC 4.4 -Wall, for instance, then I would agree to style
> rules that I might not otherwise be excited about (like the one mentinoed
> above).
 
I don't see anything wrong with this code, but as a general rule I would 
agree that it is better to be warning free if possible. This makes the 
compile neater and reduces bug reports.
 
> I would also be interested in standardizing function comment blocks.  There
> are a number of differntly styled function intro blocks evident in PLplot.
> 
> One thing I've been doing in my professional projects of late, is using
> doxygen.  I find the standard doxygen style that depends on all the '*'
> characters to be really ugly, but since I mostly code in C++, there is the
> alternative of ///, which annoys me, but not as badly as " * ", plus those
> dorky header/trailer tokens.
> 
> I've not tried doxygen on a C code base before, so I'm not sure if there are
> options that are more visibly appealilng than the standard/default.  Without
> looking into it a bit first, I'm not in a postion to propose a specific style
> for function comment blocks.  But I thought I throw out the doxygen option in
> case anyone else is interested in that, and able to summarize some of the
> options.  
> 
> Fundamentally, I like the 79-char horizontal separators for functions.  I
> think that makes the code a lot easier to read.  But I'm very annoyed by the
> /* ... */ style of multi-line C comments.  Did C99 pick up //-style comment
> to end of line?  If so, what would people think of using that in our C code
> base?  

I tend to think the 

/***********************
 * Function name
 * Description
 ***********************/

style of comment is a little fiddly to write, but is very readable and clearly 
marks out different functions. In recent years we have tended to stamp out the 
use of // comments in non-C++ code since it is not standard. If your using 
emacs with font lock mode then either is easy to read, so I suggest we stick 
with the traditional C style for maximum compatibility.
 
> Another element of style that Maurice and I have both used for nearly two
> decades now, is that in-function comments are out-dented one level.  We've
> met some vi users who complain about this, but for [X]Emacs folk, it's
> trivially easy to configure the cc-mode to do this, so that it requires no
> extra keystrokes, and just happens automatically (plus end-of-line auto
> wrapping support).  Especially combined with font locking, it really helps to
> make comments stand out in a way that lets you easily and visually separate
> the control logic and the comments thereupon.  

Again, this is not something I usually do, but I can see the sense in it.

> Unfortunately we can't do that (out-denting of comments) in Python, due to
> the indentation-as-structure-definition semantic of the language.  But I
> think it's probably basically inevitable that there will necessarily be at
> least some minor variations in adapting a style to a variety of languages.
> 
> Well, those are some of my initial thoughts in regard to Alan's comments.

No rules will fit all languages I suspect, and some will have their own 
coding style anyway. We can at least make the core code, drivers and C / 
C++ examples consistent and apply this to other languages where appropriate.

Andrew