List:Internals« Previous MessageNext Message »
From:Guilhem Bichot Date:September 23 2010 5:35pm
Subject:[STYLE] could we allow // for comments alone on their line?
View as plain text  
Hello,

http://forge.mysql.com/wiki/MySQL_Internals_Coding_Guidelines#Commenting_Code
says

     *  When writing single-line comments, the '/*' and '*/" are on the 
same line. For example:

  /* We must check if stack_size = Solaris 2.9 can return 0 here */

     * For a short comment at the end of a line, you may use either /* 
... */ or a // double slash.

I have always interpreted those rules the following way: this is permitted:

/* blah */
int x; // blih

but this is fordidden:
// blah
int x; // blih

I cannot find a good reason for this forbidding, and I find that the 
first form is less uniform than the second. I always need to remember 
that if there's no non-comment word on the line I need to use /* */ . Also,
/* comment */ adds 3 characters compared to
// comment
so if my single-line comment is close to 75 chars, with // it still fits 
into 78 chars (the line limit); but I rather have to use /* */ then it 
does not fit into one line then I fall into this other rule

"When writing multi-line comments please put the '/*' and '*/' on their 
own lines"

and then it takes 3 lines: compare
// long comment 75 chars
to
/*
   long comment 75 chars
*/

So the proposal is merely to allow
// this is a comment which is alone on its line
in C++ code.
I'm fine if we continue forbidding
// this is
// a multi-line
// comment
and require /* */ instead.

-- 
Mr. Guilhem Bichot <guilhem.bichot@stripped>
Oracle / MySQL / Optimizer team, Lead Software Engineer
Bordeaux, France
www.oracle.com / www.mysql.com
Thread
[STYLE] could we allow // for comments alone on their line?Guilhem Bichot23 Sep
  • Re: [STYLE] could we allow // for comments alone on their line?Joerg Bruehe24 Sep
    • Re: [STYLE] could we allow // for comments alone on their line?Mats Kindahl24 Sep
      • Re: [STYLE] could we allow // for comments alone on their line?Mark Leith24 Sep
      • Re: [STYLE] could we allow // for comments alone on their line?Davi Arnaut25 Sep
        • Re: [STYLE] could we allow // for comments alone on their line?Mats Kindahl25 Sep
          • Re: [STYLE] could we allow // for comments alone on their line?Davi Arnaut26 Sep
        • Re: [STYLE] could we allow // for comments alone on their line?Guilhem Bichot27 Sep
          • Re: [STYLE] could we allow // for comments alone on their line?Martin Hansson28 Sep
          • Re: [STYLE] could we allow // for comments alone on their line?Davi Arnaut28 Sep
  • Re: [STYLE] could we allow // for comments alone on their line?Ingo Struewing24 Sep
  • [STYLE] could we allow // for comments alone on their line?Michael Widenius30 Sep