[phobos] Phobos Style Guide: Commenting out code

[Jacob Carlborg]

On 2 jul 2012, at 06:36, Jonathan M Davis wrote:

> 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?

I think comments should be allowed. I prefer to use comments because most editors has a command for commenting out a piece of selected code. I don't think there's any editor that can do the same but with a "version (none)" block instead.

I would never use "version (none)" but if people like it, I have no problem with them using it. So perhaps let it be unspecified.

BTW, since you brought this up, I have a few comments:

* Mentioning of how abbreviations are written with regards to upper and lower case, i.e.

httpFoo
HTTPFoo

This has been asked about in the newsgroups several times.

* How should the licensee information look like

For example, I think it's unnecessary to repeat the license information twice. First once, using D-style, with copyright, license and author information in separate Ddco sections:

https://github.com/D-Programming-Language/phobos/blob/master/std/getopt.d#L17

Then second, using the Boost-style with the copyright, license and author information combined:

https://github.com/D-Programming-Language/phobos/blob/master/std/getopt.d#L27

Currently it seems to be a mix of these style in Phobos but I prefer to only use the Ddoc sections, like this:

https://github.com/D-Programming-Language/phobos/blob/master/std/net/isemail.d

* How should doc comments look like

-- 
/Jacob Carlborg