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

[Christian Stimming]

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