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
------------------------------------------------------------------------------
_______________________________________________
Plplot-devel mailing list
Plplot-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/plplot-devel
