[phobos] Initial Phobos style guide proposal

[Jonathan M Davis]

On 2011-03-31 08:00, Steve Schveighoffer wrote:
> >________________________________
> >From: David Simcha <dsimcha at gmail.com>
> >On Thu, Mar 31, 2011 at 9:29 AM, Steve Schveighoffer <schveiguy at yahoo.com>
> >wrote:
> >
> >One thing I've noticed about std.container, and it makes it very hard for
> >me to read:  Putting all ddoc comments with no indentation.  In
> >particular, I have a very hard time seeing where a class or struct ends. 
> >Andrei, there must be a good reason for you to do this, can you explain
> >that?  I'd really prefer that the comments are put at the same
> >indentation as the code being commented.
> >
> >>Also, can we standardize the comment style, at least for ddoc comments?
> >>I've seen a few different styles in phobos.  My favorite is:
> >>
> >>
> >>/**
> >> * comment
> >> */
> >>
> >>
> >>or
> >>
> >>/++
> >> + comment
> >> +/
> >>
> >>
> >>
> >>I do not like this:
> >>
> >>
> >>/**
> >>comment
> >>*/
> >
> >I've switched the other way recently.  The problem with your example is
> >that it's a huge pain when you go to modify the comment and need to keep
> >all those extra *'s in sync.  Furthermore, if you're using an editor with
> >syntax highlighting, I don't find distinguishing comments and code to be
> >even the slightest bit of a problem.
> 
> Keeping the *'s in sync has become second nature to me.  Plus my editor
> makes this easy.  In vim, I use 'J' to join a line to the next one, then
> 'dw' to delete the *.  Finally, I have 'K' mapped to 'gql', which in one
> keystroke, inserts all necessary line breaks for the paragraph (for 80
> chars) and automatically indents and inserts '*' prefixes.

If you use the /++ +/ commenting style, no *'s are necessary and the issue is 
completely avoided, because the /++ and +/ are the only markers that the 
comment needs, and the editors don't go and add extra +'s or *'s. Personally, 
I don't understand why you'd _want_ to have all of those extra *'s.

- Jonathan M Davis