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 _______________________________________________ phobos mailing list [email protected] http://lists.puremagic.com/mailman/listinfo/phobos
