This post concerns what style we should adopt for our multiline comments. I think most people agree that using /* ... */ for commentary is a poor idea (see, for example, the discussion of the missing trailing */ issue below). Thus, for C++ we should probably drop the /* */ form of commentary altogether and use // instead. I also think we should consider doing that for our C code as well. Certainly, the C99 standard supports the // style of comments in C code as does gcc. Is anyone here aware of any modern C compiler that does not understand the // form of comment?
If a consensus forms here to move over to the // form for our C code (as well as C++) then let's do that (probably with the aid of uncrustify if we can get the developers there to support that style option). The big advantage of that choice is you can skim the rest of this which concerns style issues with the /* .... */ form of comment. :-) For C code and the /*...*/ form of comment we have the choice of the asterisked form /* * Some comments... * More comments.... */ or the unasterisked form /* Some comments... More comments.... */ It turns out the choice between the two above styles is purely a matter of style with no practical consequences. Previous discussion of this style issue included (what were thought at the time to be) practical concerns about the doxygen requirements, but from http://www.stack.nl/~dimitri/doxygen/docblocks.html, the unasterisked form, e.g., /*! ... doxygen directives and text ... */ is fine for doxygen style comments (as well as // and many other forms). I have done one small local test with plpage.c (the source code that Werner has "doxygenized") that also confirms that for doxygen version 1.5.6-2. So it appears our choices (if we decide to continue with /*...*/ for now) are to (1) Force all multiline comments to have leading asterisks. That is what we do now by setting cmt_star_cont to true in uncrustify.cfg. (2) Ignore whether there are leading asterisks or not. I have checked that is what happens if we changed cmt_star_cont to false in uncrustify.cfg. So this option would leave our current multi-line commentary with leading asterisks alone, but allow future change to not have leading asterisks. (3) Force all multiline comments to not have leading asterisks. That would require an uncrustify change to allow that possibility, but from the great activity in uncrustify development, and their goal of controlling all style decisions with uncrustify, I think such a wish-list item would be quickly accepted by them (especially if we sent a patch to that effect). I am currently experiencing a nasty emacs issue where if you attempt to fill multi-line commentary to even out the right-hand side a bit, then what were leading asterisks are scattered throughout the commentary text. If the emacs gurus here have no solution for this, then it provides a strong motivation for (3). I can see one advantage of leading asterisks which is to guard against the possibility of invalid multiline comments where the leading "/*" is missing a trailing "*/" so that the effective comment goes on for many lines of code. But in my opinion a far better solution for this issue is to move from the /*...*/ form of comments to the // form of comments. I look forward to your further discussion on whether to move now to the // form or wait on that and attempt instead to deal with the /*...*/ leading asterisk issue. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); PLplot scientific plotting software package (plplot.org); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ Throughout its 18-year history, RSA Conference consistently attracts the world's best and brightest in the field, creating opportunities for Conference attendees to learn about information security's most important issues through interactions with peers, luminaries and emerging and established companies. http://p.sf.net/sfu/rsaconf-dev2dev _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
