Re: [Plplot-devel] A comment style issue
On 2010-02-08 14:20-0800 Alan W. Irwin wrote: > On 2010-01-22 08:39+0100 Arjen Markus wrote: > >> Hi Alan, >> >> I have so far been using the /* ... */ for most, if not all, my C code. >> The reason being that it was C, not C++. As all compilers that are >> relevant to me are indeed accepting this by default, I have no objection >> whatsoever to adopting //. In fact, it makes it much clearer what is and >> what is not comment. > > It's been some time now with no further comments on this thread so I would > like to follow up on this topic with a decision. The consensus (with no > dissenting opinions) seems to be that // comments would be fine for C code. > So I intend to use // style comments from now on in C code, and I encourage > their use with other developers. Of course, converting our existing > comment-style to the // form would be a pain if done by hand. Therefore, in > the interests of uniform style I am going to inquire with the uncrustify > developers whether they would be willing to implement a style option for > both C and C++ code that converts all single and multiple line /*... */ > comments to the // form. Hmmm. No response so far on the uncrustify list. So we may have to do the conversion to // form using a special script. 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 __ -- SOLARIS 10 is the OS for Data Centers - provides features such as DTrace, Predictive Self Healing and Award Winning ZFS. Get Solaris 10 NOW http://p.sf.net/sfu/solaris-dev2dev ___ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
Re: [Plplot-devel] A comment style issue
On 2010-01-22 08:39+0100 Arjen Markus wrote: > Hi Alan, > > I have so far been using the /* ... */ for most, if not all, my C code. > The reason being that it was C, not C++. As all compilers that are > relevant to me are indeed accepting this by default, I have no objection > whatsoever to adopting //. In fact, it makes it much clearer what is and > what is not comment. It's been some time now with no further comments on this thread so I would like to follow up on this topic with a decision. The consensus (with no dissenting opinions) seems to be that // comments would be fine for C code. So I intend to use // style comments from now on in C code, and I encourage their use with other developers. Of course, converting our existing comment-style to the // form would be a pain if done by hand. Therefore, in the interests of uniform style I am going to inquire with the uncrustify developers whether they would be willing to implement a style option for both C and C++ code that converts all single and multiple line /*... */ comments to the // form. 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 __ -- The Planet: dedicated and managed hosting, cloud storage, colocation Stay online with enterprise data centers and the best network in the business Choose flexible plans and management services without long-term contracts Personal 24x7 support from experience hosting pros just a phone call away. http://p.sf.net/sfu/theplanet-com ___ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
Re: [Plplot-devel] A comment style issue
Hi Alan, I have so far been using the /* ... */ for most, if not all, my C code. The reason being that it was C, not C++. As all compilers that are relevant to me are indeed accepting this by default, I have no objection whatsoever to adopting //. In fact, it makes it much clearer what is and what is not comment. Regards, Arjen On 2010-01-21 23:03, Alan W. Irwin wrote: > 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
Re: [Plplot-devel] A comment style issue
Hi, Alan,
On Jan 21, 2010, at 22:39 , Alan W. Irwin wrote:
>> I certainly find the // comments convenient, but I recently ran
>> into a small annoyance on a project with a manually maintained
>> Makefile. I found that I needed to use the gcc compiler option...
>>
>> -std=gnu99
>>
>> ...in order to be able to use // comments and some other "basics"
>> like usleep and getopt.
>
> I just did a test of a // comment with gcc (without any special
> options),
> and it compiled fine. Could you try to confirm that for your version
> of gcc as well?
Yes, it recognizes // comments fine with no -std option, but then it
gives a warning about round(). Using -std=c99 (as indicated by "man
3 round") then gives a warning about usleep(). Using -std=gnu99 gets
it all to work. FWIW, this is with gcc 4.1.2 on CentOS 5.3.
$ gcc --version
gcc (GCC) 4.1.2 20080704 (Red Hat 4.1.2-44)
Copyright (C) 2006 Free Software Foundation, Inc.
This is free software; see the source for copying conditions. There
is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.
$ cat foo.c
#include
#include
#ifndef NO_COMMENT
// Test usleep and round functions
#endif
double foo(double x)
{
usleep(1);
return round(x);
}
$ gcc -c -o /dev/null foo.c
foo.c: In function 'foo':
foo.c:8: warning: incompatible implicit declaration of built-in
function 'round'
$ gcc -std=c89 -c -o /dev/null foo.c
foo.c:5: error: expected identifier or '(' before '/' token
# ifndef out the // comment
$ gcc -std=c89 -DNO_COMMENTS -c -o /dev/null foo.c
(no complaints, but no // comments either)
$ gcc -std=c99 -c -o /dev/null foo.c
foo.c: In function 'foo':
foo.c:7: warning: implicit declaration of function 'usleep'
$ gcc -std=gnu99 -c -o /dev/null foo.c
(no complaints and with // comments!)
I should note that gcc 4.3.4 (on my Mac, installed via macports)
compiles the above foo.c without any -std options (and with the //
comments).
Like I said earlier, I think cmake should be able to handle any
compiler specific issues, so I don't think my whining about this
should dissuade you from changing to // comments.
Dave
--
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
Re: [Plplot-devel] A comment style issue
On 2010-01-21 21:08-0800 David MacMahon wrote: > Hi, Alan, > > On Jan 21, 2010, at 14:03 , Alan W. Irwin wrote: > >> 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? > > I certainly find the // comments convenient, but I recently ran into a small > annoyance on a project with a manually maintained Makefile. I found that I > needed to use the gcc compiler option... > > -std=gnu99 > > ...in order to be able to use // comments and some other "basics" like usleep > and getopt. I just did a test of a // comment with gcc (without any special options), and it compiled fine. Could you try to confirm that for your version of gcc as well? 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
Re: [Plplot-devel] A comment style issue
Hi, Alan, On Jan 21, 2010, at 14:03 , Alan W. Irwin wrote: > 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? I certainly find the // comments convenient, but I recently ran into a small annoyance on a project with a manually maintained Makefile. I found that I needed to use the gcc compiler option... -std=gnu99 ...in order to be able to use // comments and some other "basics" like usleep and getopt. Using just "c99" instead of "gnu99" apparently excludes some (commonly used, IMHO) functionality. I presume that cmake would discover what the user's compiler requires in order to build the PLplot code, so I don't think this would be an issue for PLplot. > 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. Not quite, IMHO. The former form (with leading asterisks on every line) offers a little more information to someone who is grepping through the code and gets one one line from a multi-line comment. The leading asterisk is a visual cue/clue that the line is from a comment. It's amazing how some comments taken out of context this way can look like actual code! :-) Of course, this is perhaps yet another reason to go with // comments in the first place. > 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't help you with that specifically (I use Vim), but I suspect all major editors can deal with reflowing all kinds of comments once they are suitably "trained". > 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. In the final analysis, I'm pretty agnostic about source code styles (including comments). Different projects have different styles, so I've learned to adapt to the local customs. When in Rome... Hope this helps, Dave -- 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
