[phobos] Phobos Style Guide: Commenting out code

[Jonathan M Davis]

Okay. It's long passed time that the remaining issues in my pull request to 
the D style guide are addressed so that we can get it updated on the site.

My request:

https://github.com/D-Programming-Language/d-programming-language.org/pull/16

Current:

http://dlang.org/dstyle.html

One of the outsanding issues is the section on comments. I removed it, because 
I see it as pointless and adding extra restrictions that we don't need - such 
as requiring that block comments use /* */ or /+ +/ rather than // on each 
line. I see no added value in such requirements, and Phobos in general doesn't 
necessarily follow them as it is. However, the big one is version(none).

The guide currently says that you should use version(none) to comment out 
blocks of code rather than actually commenting them out. We haven't been 
following that rule, and I don't see any real value in it. The _only_ value 
AFAIK is that the compiler will check it syntactically if it's in a 
version(none) block while it won't if it's in a comment. The comment is 
effectively unmaintained in either case, and you'll have to fix it up (or at 
least make sure that it's valid) if you uncomment it later. So, I don't see 
any reason to require that version(none) be used rather than a comment.

And personally, I think that commenting code out with an actual comment is 
better, because then editors will syntax highlight it as commented out rather 
than coloring it exactly the same as they color valid code. With 
version(none), the code will look as if it's being used when it's not, whereas 
it's immediately obvious with an actual comment.

 I say leave it up to the developer who commented out the code which they 
prefer and remove the section on comments from the style guide completely. But 
we need some sort of consensus on this before we can make the change. So, what 
do the rest of you think?

- Jonathan M Davis