My votes/comments are below. I generally use vim so I prefer
vim-friendly guidelines. I hope that doesn't affect my standing in
the PLplot community :-)
On Fri, Jun 26, 2009 at 2:03 PM, Andrew
Ross<andrewr...@users.sourceforge.net> wrote:
> On Thu, Jun 25, 2009 at 10:44:09PM -0500, Geoffrey Furnish wrote:
>> 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.
I agree as well. (3) may have a little too much whitespace for my
taste. I think this reads more easily:
if (a != 0 && (b == 2 || c == 2 - x)) ...
That said, I am far happier with either of these than the "rather
than" example above.
>> 4) Braces:
>>
>> if ( condition )
>> {
>> ...
>> }
>> else
>> {
>> ...
>> }
>
> I have a slight personal preference for:
>
> if ( condition ) {
> ...
> }
> else {
> ...
> }
>
> but I'm happy to live with the consensus.
I agree with Andrew on this.
>> 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 again agree with Andrew on this.
>> 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.
Agreed.
>> 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.
I would prefer not to do this. As Maurice comments in his reply,
syntax highlighting handles this quite nicely.
>> 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.
I think, where appropriate, the standards within each of the supported
PLplot languages should hold. "Where appropriate" is probably best
determined by the author(s) of each language binding. Sticking as
close as possible to the feel of the core PLplot standards is probably
best.
A line length of 80 characters is a fairly common standard. I do not
think that it needs to be a hard rule, but I find that it helps keep
up readability in the general case.
Should a standard convention for naming functions/values/macros be
set? For example, most of the PLplot C functions are prefixed by
"pl", but a few have a "pl_" prefix. Similarly, the spelling of
function names range noticeably in their verbosity. API growth will
likely be slow, but a standard would be helpful. This has come up
recently is in the HAVE_* name clashes. A standard naming scheme
should help address questions like this.
Hez
--
Hezekiah M. Carty
Graduate Research Assistant
University of Maryland
Department of Atmospheric and Oceanic Science
------------------------------------------------------------------------------
_______________________________________________
Plplot-devel mailing list
Plplot-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/plplot-devel
