[GNC-dev] Minor coding style discussion: C++ and comments

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

[GNC-dev] Minor coding style discussion: C++ and comments

Christian Stimming-4
Dear developers,

some years ago we had a longer discussion about our coding style guide,
especially as we started with more C++ parts in the project. Last time we
discussed this a bit more was in 2014 [1], and the result was summarized in
the wiki page  https://wiki.gnucash.org/wiki/CodingStandard

However, as C++ becomes more common for the actual work throughout gnucash, we
might need to add or clarify a few points there. In my opinion this is really
a minor issue, as everyone of us will be able to read and write any coding
style, regardless which one we prefer. It is just nicer to read if there is a
larger level of consistency. Having said that, one such thing is the way of
writing multi-line comments in C++ code. Should this be:

// This is
// a multi-line comment (C++ style)

or rather in C style

/* This is
   a multi-line comment (C style) */

with additionaly variants of those? John and I discussed this question
shortly. There used to be an advice on the wiki page but different from the
other points this hasn't been discussed here on the mailing list [2]. Hence
John and I agreed it should be raised on the mailing list.

My proposal is to use the C++ style option in the source code. In any case the
style should be consistent throughout the source files, i.e. someone would
need to transform the style that is different from the agreed one.

Also, the doxygen comments in the headers, should those stick to the doxygen
proposal

/** Some doxygen
    multi-line comment (C style, doxygen) */

or should we switch to something different? There are multiple options
possible, including

/// Some doxygen multi-line
/// comment (C++ style, doxygen)

but on the other hand we don't have many C++-only headers so far. I'd rather
stick with the old style as long as we usually have headers used by the C code
as well.

More ideas and voices?

Regards,

Christian


[1] https://lists.gnucash.org/pipermail/gnucash-devel/2014-September/038027.html 
[2] John said: The only discussion about commenting style I found was
https://lists.gnucash.org/pipermail/gnucash-devel/2008-January/thread.html#22321 (the thread finishes in February,
https://lists.gnucash.org/pipermail/gnucash-devel/2008-February/022375.html); 
before we considered C++; another discussion about C++ style begins at
https://lists.gnucash.org/pipermail/gnucash-devel/2014-September/038027.html 
but doesn’t mention comments
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Minor coding style discussion: C++ and comments

John Ralls


> On Jun 23, 2018, at 2:16 PM, Christian Stimming <[hidden email]> wrote:
>
> Dear developers,
>
> some years ago we had a longer discussion about our coding style guide,
> especially as we started with more C++ parts in the project. Last time we
> discussed this a bit more was in 2014 [1], and the result was summarized in
> the wiki page  https://wiki.gnucash.org/wiki/CodingStandard
>
> However, as C++ becomes more common for the actual work throughout gnucash, we
> might need to add or clarify a few points there. In my opinion this is really
> a minor issue, as everyone of us will be able to read and write any coding
> style, regardless which one we prefer. It is just nicer to read if there is a
> larger level of consistency. Having said that, one such thing is the way of
> writing multi-line comments in C++ code. Should this be:
>
> // This is
> // a multi-line comment (C++ style)
>
> or rather in C style
>
> /* This is
>   a multi-line comment (C style) */
>
> with additionaly variants of those? John and I discussed this question
> shortly. There used to be an advice on the wiki page but different from the
> other points this hasn't been discussed here on the mailing list [2]. Hence
> John and I agreed it should be raised on the mailing list.
>
> My proposal is to use the C++ style option in the source code. In any case the
> style should be consistent throughout the source files, i.e. someone would
> need to transform the style that is different from the agreed one.
>
> Also, the doxygen comments in the headers, should those stick to the doxygen
> proposal
>
> /** Some doxygen
>    multi-line comment (C style, doxygen) */
>
> or should we switch to something different? There are multiple options
> possible, including
>
> /// Some doxygen multi-line
> /// comment (C++ style, doxygen)
>
> but on the other hand we don't have many C++-only headers so far. I'd rather
> stick with the old style as long as we usually have headers used by the C code
> as well.
>
> More ideas and voices?
>
> Regards,
>
> Christian
>
>
> [1] https://lists.gnucash.org/pipermail/gnucash-devel/2014-September/038027.html 
> [2] John said: The only discussion about commenting style I found was
> https://lists.gnucash.org/pipermail/gnucash-devel/2008-January/thread.html#22321 (the thread finishes in February,
> https://lists.gnucash.org/pipermail/gnucash-devel/2008-February/022375.html); 
> before we considered C++; another discussion about C++ style begins at
> https://lists.gnucash.org/pipermail/gnucash-devel/2014-September/038027.html 
> but doesn’t mention comments

A wee clarification: Reference 2 is a discussion of 6 possible commenting styles for C code; it occurred several years before we began to adopt C++. It’s worth reading both to see all 6 proposals and the various arguments for and against each. The argument about C compilers not supporting C++-style is now obsolete. The C99 spec allows that style of comments and any compiler that supports C++11 will also support C99, though we may need to set -std=C99 in CMAKE_C_FLAGS to avoid whining.

There are also a couple more ways to delineate doxygen comments described at http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html <http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html>.

For the record, I don’t care as long as all comments in a file use the same style and a single commit is used to convert the comments in a particular file and that commit has no other changes.

Regards,
John Ralls




_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel
Reply | Threaded
Open this post in threaded view
|

Re: [GNC-dev] Minor coding style discussion: C++ and comments

Colin Law
On 23 June 2018 at 23:49, John Ralls <[hidden email]> wrote:
> ...
> For the record, I don’t care as long as all comments in a file use the same style and a single commit is used to convert the comments in a particular file and that commit has no other changes.

I cannot see the point in wasting time changing the format in existing
code. When it comes to understanding existing code, the comment format
will make no difference to any developer sufficiently experienced to
understand code as complex as gnucash.  In addition there is always
the slight possibility of accidentally changing code so possibly
introducing bugs.  Surely there are more important things to do.

Colin
_______________________________________________
gnucash-devel mailing list
[hidden email]
https://lists.gnucash.org/mailman/listinfo/gnucash-devel