[phobos] Initial Phobos style guide proposal

[Steve Schveighoffer]

----- 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'sjusthardertoread.

> 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.

-Steve