Notes on the Phobos style guide

[Jonathan M Davis]

This is, unfortunately, the sort of thing that can get pretty opinionated, and 
there are plenty of people who hate having to write code in any style other than 
their own, but unfortunately, you do sometimes need at least some sort of 
stylistic guidelines or things can become a mess.

On Monday, August 16, 2010 15:15:47 bearophile wrote:
> Few comments of mine about this, written by Andrei:
> http://lists.puremagic.com/pipermail/phobos/2010-August/001757.html
> 
> > * Generally the prevalent Phobos (and I hope D) style is to declare
> > local values as late as possible.
> 
> Good.
[snip]

Personally, I really hate having all of the variables declared at the top of the 
function and consider it bad style. You'll have fewer bugs if you can avoid 
declaring variables before you're actually read to initialize it with a real 
value (though D's default initialization of all variables mitigates this 
somewhat).

> 
> > * In D, use of auto is recommended unless you want to make a
> > specific point by mentioning the type.
> 
> This is where I don't agree.
[snip]

I'm increasingly in the pro-auto camp, but I do think that you need to use it 
wisely. In most cases, I think that it's quite clear what type you're dealing 
with, but if there really is going to be an issue with that, then the exact type 
should be used. Overall, I do think that auto should be the default - 
particularly for smaller functions where it's really easy to see what's going on 
- but there are exceptions.

> > * Phobos currently uses full bracing after if, while etc. I've tried to
> > follow that but on occasion I slip. I'm not sure whether we should
> > enforce such rules; this might be a good time to discuss that.
> 
> I don't have a definite opinion on this. I am just glad Python has *solved*
> this class of problems, and it removes some braces-related bugs.

Personally, I _like_ having braces in D, but I also dislike pointless braces. I 
usually only put them if the condition spans more than one line or if the body 
spans more than one line (whether it's one statement or multiple). I hate having 
to put extra braces, but I've had to work in shops before where braces were 
always required. 

> > * Generally I encourage economy of vertical space, e.g.
> > auto imp = new File.Impl(fp, 1, host ~ ":" ~ to!string(port));
> > f.p = imp;
> > =>
> > f.p = new File.Impl(fp, 1, host ~ ":" ~ to!string(port));
> 
> It's a matter of readability too.
> I generally don't like this:
> 
> if (...) bar();
> 
> I generally prefer (as the Python PEP 8 suggests):
> 
> if (...)
>     bar();
> 
> But in some situations (for example when there are many small short
> successive ifs), the one-line version is OK:
> 
> if (cond1)     bar();
> if (condi2)    baz();
> if (co3)       spam();
> if (condtion4) x++;

I hate one line if statements, but I don't like pointless variables either. I 
also dislike the extra spacing that you have around your parens. I do find it 
interesting, however, that Andrei lists both always using braces and saving 
vertical space, since they're pretty contradictory.

In any case, ultimately, Phobos likely does need some sort of simple style guide 
that ensures that the code is at least relatively uniform, but it's pretty much 
a guarantee that whatever is picked is going to annoy at least some portion of 
the folks that have to deal with it. But ultimately, it only really matters to 
the Phobos devs, since they're the ones who are going to be working on the code. 
Obviously, in my own code, I'm just going to code the way that I like, and I see 
no point in any kind of standard D style guide with regards to braces and other 
visual elements to relate primarily to how the code looks rather than what it 
does.

As for stuff like auto, however, I'd argue that that isn't entirely a stylistic 
issue. Part of that is a question of good practices rather than having something 
that looks nice and is readable. And I'm not aware of any official anything 
anywhere that talks about what is and isn't considered good practice in D. We 
should probably get something like that at some point as some of what should go 
there becomes clear. Though I'm not sure whether there's enough collective 
experience with D2 at this point (especially considering that it's only recently 
stop having massive changes to it) to really get much of a list together that's 
particularly specific to D rather than what you'd do in similar languages like 
C++ or C#.

- Jonathan M Davis