[phobos] Phobos Style Guide: Commenting out code

[Jonathan M Davis]

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