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

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
phobos@puremagic.com
http://lists.puremagic.com/mailman/listinfo/phobos

On Monday, July 02, 2012 12:56:29 Jacob Carlborg wrote:
> * 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.

I intend to add that. I was just looking to address the comments issue before
making any more updates, because it was one of the few issues where there was
disagreement and needs to be resolved.

> * 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#L1 7
> 
> 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#L2 7
> 
> 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

They should only list them once, but I'm not sure that that's something that actually needs to be mentioned in the style guide. I believe that it's only older stuff which has it twice.

> * How should doc comments look like

What are you looking for here? The comment markers must be /++ +/, /** */, or /// per the language, so the only reason to mention that is if we required a specific one of them to be used, and we're not in agreement on which style to use, but since it doesn't affect the docs themselves, I don't see any reason to specify which to use. And if you're talking about what should go in the comments, what would we need to say beyond that it should say what the function does? That it needs to have examples (preferrably compilable examples)? I'm not quite sure what we'd really need to say about ddoc comments. Overall, it seems fairly obvious to me what should go in a ddoc comment - pretty much the same thing which should go in any function comment. What do you think needs further explanation or requirements?

- Jonathan M Davis
_______________________________________________
phobos mailing list
phobos@puremagic.com
http://lists.puremagic.com/mailman/listinfo/phobos

On 2 jul 2012, at 19:27, Jonathan M Davis wrote:

> On Monday, July 02, 2012 12:56:29 Jacob Carlborg wrote:
> 
> I intend to add that. I was just looking to address the comments issue before making any more updates, because it was one of the few issues where there was disagreement and needs to be resolved.

I see, good.

> What are you looking for here? The comment markers must be /++ +/, /** */, or /// per the language, so the only reason to mention that is if we required a specific one of them to be used, and we're not in agreement on which style to use, but since it doesn't affect the docs themselves, I don't see any reason to specify which to use. And if you're talking about what should go in the comments, what would we need to say beyond that it should say what the function does? That it needs to have examples (preferrably compilable examples)? I'm not quite sure what we'd really need to say about ddoc comments. Overall, it seems fairly obvious to me what should go in a ddoc comment - pretty much the same thing which should go in any function comment. What do you think needs further explanation or requirements?


It's fairly obvious that it needs to be ddoc comments, otherwise it won't work. But there are various styles that can be used:

* Using single line comments as multiline comments:

/// Multiline /// comment

* Using multiline comments:

/**
Multiline
comment
*/

* Using multiline comments in Java style:

/**
 * Multiline
 * comment
 */

* Using multiline comment for single line comment

/** Single line comment */

/++
Nested comment style
+/

* Putting single line comments before or after the symbol

Then when various sections that is not consistently used, like:

* Return
* Params
* Examples
* See_Also
* Standards
* Throws

We could have guidelines saying when these sections should and shouldn't be used. I don't know how to picky we want to be with the documentation but these were the things I had in mind.

-- 
/Jacob Carlborg

On Monday, July 02, 2012 21:57:54 Jacob Carlborg wrote:
> It's fairly obvious that it needs to be ddoc comments, otherwise it won't work. But there are various styles that can be used:
> 
> * Using single line comments as multiline comments:
> 
> /// Multiline
> /// comment
> 
> * Using multiline comments:
> 
> /**
> Multiline
> comment
> */
> 
> * Using multiline comments in Java style:
> 
> /**
> * Multiline
> * comment
> */
> 
> * Using multiline comment for single line comment
> 
> /** Single line comment */
> 
> /++
> Nested comment style
> +/
> 
> * Putting single line comments before or after the symbol

Well, honestly, I _don't_ want to require a particular style for ddoc comments. I always use /++ +/ and hate /** */ (especially when the * is at the front of every line), but there are others who prefer /** */, so we're just going to get into an argument if we try and mandate that. I say just let the programmer decide which to use. It has no effect on the generated ddoc, and most of the style guide focuses on stuff that affects the API, not how the code itself is styled.

> Then when various sections that is not consistently used, like:
> 
> * Return
> * Params
> * Examples
> * See_Also
> * Standards
> * Throws
> 
> We could have guidelines saying when these sections should and shouldn't be used. I don't know how to picky we want to be with the documentation but these were the things I had in mind.

I don't know. I'm not sure that it's worth trying to say much on these. I don't know what we'd say. On the whole, what we've been doing has been working. I'm not against us coming up with some guidelines on these, but I don't know what they'd be, and I'd prefer to make that a separate discussion beyond sorting out my proposed changes. Guidelines like that can be added later.

- Jonathan M Davis
_______________________________________________
phobos mailing list
phobos@puremagic.com
http://lists.puremagic.com/mailman/listinfo/phobos

On 2 jul 2012, at 22:13, Jonathan M Davis wrote:
> I don't know. I'm not sure that it's worth trying to say much on these. I don't know what we'd say. On the whole, what we've been doing has been working. I'm not against us coming up with some guidelines on these, but I don't know what they'd be, and I'd prefer to make that a separate discussion beyond sorting out my proposed changes. Guidelines like that can be added later.


Ok, fair enough.

-- 
/Jacob Carlborg

_______________________________________________
phobos mailing list
phobos@puremagic.com
http://lists.puremagic.com/mailman/listinfo/phobos

On Sunday, July 01, 2012 21:36:03 Jonathan M Davis wrote:
> So, what do the rest of you think?

Is no one else going to comment on this? I guess that summer is a bad time to try and get any kind of consensus out of the Phobos devs, since too many of them are busy with other stuff... We really should sort this out soon though.

- Jonathan M Davis
_______________________________________________
phobos mailing list
phobos@puremagic.com
http://lists.puremagic.com/mailman/listinfo/phobos