[phobos] Initial Phobos style guide proposal

[Jonathan M Davis]

On 2011-03-31 11:54, Steve Schveighoffer wrote:
> ----- Original Message -----
> 
> > From:Jonathan M Davis <jmdavisProg at gmx.com>
> > 
> > On 2011-03-31 10:14, Steve Schveighoffer wrote:
> > > >________________________________
> > > >From: Jonathan M Davis <jmdavisProg at gmx.com>
> > > >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.
> > > 
> > > The * aren't necessary in the /** */ comment style either.  All it does
> > 
> > is
> > 
> > > make the whole block stand out as a comment vs. the open and close tag.
> > > 
> > > /+ and +/ would have the same issue of low visibility.
> > 
> > Well, many editors shove in the extra *'s on every line, but they won't
> > do
> > that with /++ +/.
> 
> in vim, I had to turn on the feature of having the *'s inserted, it wasn't
> there by default.  Yes many editors do that by default, but an editor is
> usually configurable in that respect.  The only reason /+ doesn't insert +
> by default is because it's not a commonly known comment style.
> 
> > And I don't understand problems with visibility and ddoc
> > comments, since a ddoc comments shouldn't usually be long enough that it
> > doesn't fit on the screen (though obviously some won't be - such as
> > in-depth
> > module ddoc comments), and other than examples, it's pretty clear that
> > it's
> > _not_ code. The only exception that I can really think of is when you
> > have a long example, and even then, the extra -'s make it clear that
> > it's an example.
> > Are you afraid of not being able to distinguish between a regular comment
> > and a ddoc comment? Since ddoc comments only go above declarations, I
> > wouldn't have thought that that would be a problem.
> 
> The problem I have is *seeing* the comments as comments.  The /* or /+ tags
> do not stick out as much when they are inline with the comments
> themselves.  It's just the way the human brain works -- it's good and
> distinguishing things that are separated, but if things are close together
> and do not have distinct lines, they look like the same thing. 
> Icouldalsowriteeverythingwithoutspaces,andyoucouldreadit,butit'sjustharder
> toread.
> 
> > So, if you're complaining about the low visibility of /++ +/, I don't
> > understand that. And isn't the whole point of having /++ +/ in the
> > language was for ddoc comments, with /** */ being accepted because it's
> > use in Java?
> 
> The whole point of /+ +/ was to provide nested comments.  In C:
> 
> /* opens a comment
> /* does not do anything
> */ closes the comment
> */ is a syntax error
> 
> But /+ allows nesting:
> 
> /+ opens a comment
> /+ nests a comment inside the outer comment
> +/ closes the inner comment
> +/ closes the outer comment
> 
> The idea was to leave the C behavior for /* to aid in porting C programs
> and still provide a way to have properly nested comments.

/+ +/ yes. However, I was referring to /++ +/. It was my understanding that 
/++ +/ was created with the idea of it being the way to do ddoc and that /** 
*/ was added, because that's what Java uses. But I could have misunderstood.

I take it that you don't have syntax highlighting on at all then? Since pretty 
much _any_ code editor is going to mark comments in a different color unless 
you tell it not to, and since you're apparently using /** */, you're not going 
to run into problems with it not being supported due to it being D-only.

- Jonathan M Davis