> On Jun 23, 2018, at 2:16 PM, Christian Stimming <christ...@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 _______________________________________________ gnucash-devel mailing list gnucash-devel@gnucash.org https://lists.gnucash.org/mailman/listinfo/gnucash-devel
