Wine code comments

[John Voltz]

Hi everyone,

I have a question about comments in the Wine code. I noticed while
tracking down a bug that a lot of the code comments are using the
block comment marker /*. This is a royal pain when trying to comment
out large sections of code where there are a bunch of /* foo */
comments. Why is this allowed? Is there are way around it without
having to change them all to //?

Regards,

John Voltz

[Erich Hoover]

On Fri, Jun 4, 2010 at 2:35 PM, John Voltz  wrote:
> ...
> I have a question about comments in the Wine code. I noticed while
> tracking down a bug that a lot of the code comments are using the
> block comment marker /*.
> ...

See the wiki page on patches:
http://wiki.winehq.org/SubmittingPatches

Particularly, the section entitled "Avoid C++, C99 and non-portable C
constructs."

Erich Hoover
[e-mail]

[Andrew Nguyen]

On Fri, Jun 4, 2010 at 3:35 PM, John Voltz  wrote:
> Is there are way around it without having to change them all to //?

For private, ad-hoc use, you could possibly use a preprocessor #if 0
block to achieve the desired comment effect.

[James McKenzie]

John Voltz wrote:
> Hi everyone,
>
> I have a question about comments in the Wine code. I noticed while
> tracking down a bug that a lot of the code comments are using the
> block comment marker /*. This is a royal pain when trying to comment
> out large sections of code where there are a bunch of /* foo */
> comments. Why is this allowed? Is there are way around it without
> having to change them all to //?

Simple answer:  We use 'c' comment convention because some compilers 
choke on the C++ style.

You could use #if (0) and should use this to mark out possible locations 
for buggy code as it was noted elsewhere.  Using /* and */ is not good 
coding practice to comment out code.

James McKenzie

[Frédéric Delanoy]

On Sat, Jun 5, 2010 at 05:38, James McKenzie wrote:
> John Voltz wrote:
> > Hi everyone,
> >
> > I have a question about comments in the Wine code. I noticed while
> > tracking down a bug that a lot of the code comments are using the
> > block comment marker /*. This is a royal pain when trying to comment
> > out large sections of code where there are a bunch of /* foo */
> > comments. Why is this allowed? Is there are way around it without
> > having to change them all to //?
>
> Simple answer:  We use 'c' comment convention because some compilers choke
> on the C++ style.
>
> You could use #if (0) and should use this to mark out possible locations
> for buggy code as it was noted elsewhere.  Using /* and */ is not good
> coding practice to comment out code.
>
> James McKenzie
> (E. Hoover)
> Particularly, the section entitled "Avoid C++, C99 and non-portable C
> constructs."

Actually, aside from debugging functions, and stuff in headers files, "if
(0)" would be more portable than "#if 0", with the additional advantage that
it leads to less code rot, since obsolete code tends to be deleted earlier,
and not simply forgotten.

Besides, it shouldn't incur any runtime penalty, since "if (0)" blocks are
typically discarded at compile time.

What do you think about it?

Frédéric

[James McKenzie]

Frédéric Delanoy wrote:
> On Sat, Jun 5, 2010 at 05:38, James McKenzie 
> <[e-mail] > wrote:
> John Voltz wrote:
>
>     Hi everyone,
>
>     I have a question about comments in the Wine code. I noticed while
>     tracking down a bug that a lot of the code comments are using the
>     block comment marker /*. This is a royal pain when trying to
>     comment
>     out large sections of code where there are a bunch of /* foo */
>     comments. Why is this allowed? Is there are way around it without
>     having to change them all to //?
>
>
> Simple answer:  We use 'c' comment convention because some
> compilers choke on the C++ style.
>
> You could use #if (0) and should use this to mark out possible
> locations for buggy code as it was noted elsewhere.  Using /* and
> */ is not good coding practice to comment out code.
>
>  James McKenzie
>
>
> > (E. Hoover)
> > Particularly, the section entitled "Avoid C++, C99 and non-portable C
> > constructs."
>
> Actually, aside from debugging functions, and stuff in headers files, 
> "if (0)" would be more portable than "#if 0", with the additional 
> advantage that it leads to less code rot, since obsolete code tends to 
> be deleted earlier, and not simply forgotten.
>
> Besides, it shouldn't incur any runtime penalty, since "if (0)" blocks 
> are typically discarded at compile time.

If that works better, then use it.  The OP was trying to block out 
sections of code that were causing problems to attempt isolate and then 
fix them.

Some problems are introduced just because the API code is incomplete and 
needs a little 'filling out' with properly designed and engineered 
code.  This cannot be iffed out.
> What do you think about it?

Also if (0)'d code should have a comment block on when and why it was 
removed and what must be done to re-incorporate it and if someone is 
working on it, a name and durable contact information.  Also, an 
anticpated completion date, if known, should be entered.  Reliance on a 
particular release is not sufficient.

James McKenzie

[Octavian Voicu]

2010/6/5 James McKenzie :
> Also if (0)'d code should have a comment block on when and why it was
> removed and what must be done to re-incorporate it and if someone is working
> on it, a name and durable contact information.  Also, an anticpated
> completion date, if known, should be entered.  Reliance on a particular
> release is not sufficient.

Isn't that what `git blame' is for?
Extra comments can go in the commit that introduces the if (0).

Octavian

[James McKenzie]

Octavian Voicu wrote:
> 2010/6/5 James McKenzie :
> > Also if (0)'d code should have a comment block on when and why it was
> > removed and what must be done to re-incorporate it and if someone is working
> > on it, a name and durable contact information.  Also, an anticpated
> > completion date, if known, should be entered.  Reliance on a particular
> > release is not sufficient.
>
> Isn't that what `git blame' is for?
> Extra comments can go in the commit that introduces the if (0).

Git is a realitively new product.  Wine has been around before this was 
released.  Some of the commented out code has no one in git to blame....

Also, if I were looking at this code from a pure security standpoint 
(which I can do), git blame is NOT VALID.  Thus, I stand on my original 
statement:  If you put it there, there should be comments IN THE CODE.  
If you blocked something out, you should take ownership.

Sorry, AJ, but that is a legal stance, not a practical one.

James McKenzie

[John Voltz]

Thanks for all the input. I forgot about using #if (0). That will make
life much easier.

John