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

[John Ralls]

> On Jun 23, 2018, at 2:16 PM, Christian Stimming <christian at cstimming.de> 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