www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Notes on the Phobos style guide

reply bearophile <bearophileHUGS lycos.com> writes:
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.
Defining variables at the top of the function/method is positive because it
makes the code tidy and it's easy to see in a moment all variables used
(Pascal-like languages nearly enforce this). But defining them as close as
possible to their usage point has usually bigger advantages that I don't list
here. But as usual all rules need to be used in a flexible way.

On the other hand global variables/constants are global both in scope and their
definition order doesn't matter, so I think that putting them all at the top of
the module is better.



 * 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. "auto" is very handy. When you have complex types
coming out of lazy map, filter, etc, auto becomes very important, writing code
becomes simpler.

On the other hand code needs to be read too, sometimes by people that have not
written it. In this case seeing the actual types used is often better. So using
"auto" everywhere makes the code reading harder: if you aren't using an IDE
that tells you types, you sometimes need to follow the flux of the various
calls until you find what is the type, or sometimes you need to add temporary
writeln(typeof(x).stringof); inside the code to see what type it is. This
problem is common in dynamic languages.

So 'auto' can be abused, online you can find plenty of discussions about

it, but in my opinion it's bad to use it everywhere and to encourage too much
its usage. D lacks the flexibility of a dynamic language, so it's not positive
to hide too much the types of variables from the person that reads the code.



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



 * 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++;

Bye,
bearophile
Aug 16 2010
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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.
 Defining variables at the top of the function/method is positive because it
makes the code tidy and it's easy to see in a moment all variables used
(Pascal-like languages nearly enforce this). But defining them as close as
possible to their usage point has usually bigger advantages that I don't list
here. But as usual all rules need to be used in a flexible way.
 
 On the other hand global variables/constants are global both in scope and
their definition order doesn't matter, so I think that putting them all at the
top of the module is better.
 
 

 * 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. "auto" is very handy. When you have complex types
coming out of lazy map, filter, etc, auto becomes very important, writing code
becomes simpler.
 
 On the other hand code needs to be read too, sometimes by people that have not
written it. In this case seeing the actual types used is often better. So using
"auto" everywhere makes the code reading harder: if you aren't using an IDE
that tells you types, you sometimes need to follow the flux of the various
calls until you find what is the type, or sometimes you need to add temporary
writeln(typeof(x).stringof); inside the code to see what type it is. This
problem is common in dynamic languages.
 
 So 'auto' can be abused, online you can find plenty of discussions about

it, but in my opinion it's bad to use it everywhere and to encourage too much
its usage. D lacks the flexibility of a dynamic language, so it's not positive
to hide too much the types of variables from the person that reads the code.


[citation needed]

A cursory googling didn't find many discussions.

Andrei
Aug 16 2010
parent reply bearophile <bearophileHUGS lycos.com> writes:
Andrei Alexandrescu:

 [citation needed]
 A cursory googling didn't find many discussions.


The people that have designed C++0x are surely smart and expert, but they have
done some mistakes:
- the lambda is WAY over-engineered;
- and the R-value references are useful but they look too much hard for most
normal programmers (they may be useful for core library writers). I will not
appreciate R-value references in D2/D3.

'auto' in C++0x is a good and useful feature, just as it is useful in D, but as
I have explained it has real risks, so it must be used with moderation, if you
use it everywhere in the code, your code becomes harder to understand and
modify.


http://stackoverflow.com/questions/545616/why-would-var-be-a-bad-thing
http://stackoverflow.com/questions/633474/c-do-you-use-var
http://stackoverflow.com/questions/41479/use-of-var-keyword-in-c

I am sure C++0x style guides (like Google ones) will warn against an excessive
usage of 'auto'.

Bye,
bearophile
Aug 16 2010
parent reply Adam Ruppe <destructionator gmail.com> writes:
On 8/16/10, bearophile <bearophileHUGS lycos.com> wrote:

 'auto' in C++0x is a good and useful feature, just as it is useful in D, but
 as I have explained it has real risks, so it must be used with moderation,
 if you use it everywhere in the code, your code becomes harder to understand
 and modify.


I see it as the opposite: it is about the same to understand, and much
easier to modify.

For understanding, the type is determined on the right side of the
thing anyway, and is usually plainly obvious, or if not, the type
doesn't really matter. Examples of the former are new statements or
literals, and examples of the latter are a lot of the fancy ranges'
return values.

Besides, worst case, you have to scroll up a few lines to see the
original type, but it is there if you need it. It isn't like a dynamic
language where the type can be anything passed in and can change at
random at any time. It is set in one place and stays consistent.


For modification, it makes things easier since you don't need to
repeat yourself. You can make a change in one place, and that change
automatically propagates. Again, unlike dynamic languages, the type is
still consistent: if the change breaks things down the line, the
compiler will tell you, whether you use auto or not.
Aug 16 2010
parent "Steven Schveighoffer" <schveiguy yahoo.com> writes:
On Mon, 16 Aug 2010 19:29:27 -0400, Adam Ruppe <destructionator gmail.com>  
wrote:


 Besides, worst case, you have to scroll up a few lines to see the
 original type, but it is there if you need it. It isn't like a dynamic
 language where the type can be anything passed in and can change at
 random at any time. It is set in one place and stays consistent.


Or, you use an ide which tells you the type :)


 For modification, it makes things easier since you don't need to
 repeat yourself. You can make a change in one place, and that change
 automatically propagates. Again, unlike dynamic languages, the type is
 still consistent: if the change breaks things down the line, the
 compiler will tell you, whether you use auto or not.


This is the most awesome thing about auto.  It is one of the best features  
of D IMO.
Aug 16 2010
prev sibling next sibling parent reply Jonathan M Davis <jmdavisprog gmail.com> writes:
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 


- Jonathan M Davis
Aug 16 2010
next sibling parent reply bearophile <bearophileHUGS lycos.com> writes:
Jonathan M Davis:


 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.


Often you need to modify legacy C/C++/Java code, or you need to work in a team,
in such very common situations it's often better to follow some style standard.

And even if you write D code on your own, you are not truly alone, you are part
of the D community of programmers. If you write a good module you may want to
give it to the D community. Part of the success of Python comes from the ease
to find free (as in beer) already written modules able to do almost everything
that you can just add to your own programs, usually with little or no troubles.

So your Python program comes from the collection of many modules written by
other people. So even if you are writing code on your own, it's a bit like your
'team' is the whole Python (and in future hopefully D2 too) community. This is
why the uniform style of writing Python code is good for the development of the
whole community. I think Walter has written the D style page (see below)
because he has understood this some years ago.



 And I'm not aware of any official anything 
 anywhere that talks about what is and isn't considered good practice in D.


http://www.digitalmars.com/d/2.0/dstyle.html

Bye,
bearophile
Aug 16 2010
parent reply Jonathan M Davis <jmdavisprog gmail.com> writes:
On Monday, August 16, 2010 15:59:14 bearophile wrote:

 Jonathan M Davis:

 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.


 
 Often you need to modify legacy C/C++/Java code, or you need to work in a
 team, in such very common situations it's often better to follow some
 style standard.


Well, yes, but if I have a choice, I'm going to code in the manner which I like 
best - like where to place braces and where to put spaces and how many. It's
not 
like I code in obfuscated D (or C/C++/Java/whatever). I think that most people 
who are consistent in their coding style produce understandable code. The 
problem is when you have to share or when you have a really bizarre style that 
no one else understands. I see little no value in trying to enforce any kind of 
coding standard on the D community as a whole, just like I see no value in
doing 
it to the C++ community. Now, a particular _project_ - such as Phobos can
benefit 
from a particular style since you're dealing with a group of contributors, but 
with my own code - even if I make it publicly available -  there shouldn't be 
any problem in coding in my own style as long as it's reasonably readable. It's 
only when dealing with projects that it makes sense to enforce any kind of 
coding standard.

- Jonathan M Davis
Aug 16 2010
parent reply bearophile <bearophileHUGS lycos.com> writes:
Jonathan M Davis:


 I see little no value in trying to enforce any kind of 
 coding standard on the D community as a whole,


If your program is partially composed by several modules written by different
programmers, that you have found on the net (like from dsource), you will not
appreciate to see your program as an Harlequin written in ten widely different
coding styles. A more uniform coding style helps you see your program as a
single whole instead of as a puzzle, and you will need less time to modify,
debug and improve it. If you don't see the advantage of this for your D/Python
programs then maybe it's because you haven't done this yet :-)

Bye,
bearophile
Aug 16 2010
next sibling parent bearophile <bearophileHUGS lycos.com> writes:
 If you don't see the advantage of this for your D/Python programs then maybe
 it's because you haven't done this yet :-)


Sorry, my manners need to be improved.

bearophile
Aug 16 2010
prev sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
I think Jonathan was talking about the entire community, not a single
project. It's impossible for all people to accept a unified standard,
everyone has their own style and they'll most probably keep it that way.
What matters is consistency. So if you have a certain way of coding, be
consistent about it throughout your project.

On Tue, Aug 17, 2010 at 3:38 AM, bearophile <bearophileHUGS lycos.com>wrote:


 Jonathan M Davis:


 I see little no value in trying to enforce any kind of
 coding standard on the D community as a whole,


 If your program is partially composed by several modules written by
 different programmers, that you have found on the net (like from dsource),
 you will not appreciate to see your program as an Harlequin written in ten
 widely different coding styles. A more uniform coding style helps you see
 your program as a single whole instead of as a puzzle, and you will need
 less time to modify, debug and improve it. If you don't see the advantage of
 this for your D/Python programs then maybe it's because you haven't done
 this yet :-)

 Bye,
 bearophile
Aug 16 2010
prev sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
Jonathan M Davis wrote:

 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.


True, but the idea of having a D style guide goes beyond just having a standard 
for Phobos. It fills a vacuum. When there is a reasonable existing one, lots of 
organizations will simply adopt it by default rather than go to the trouble of 
reinventing their own.
Aug 16 2010
parent Brad Roberts <braddr slice-2.puremagic.com> writes:
On Mon, 16 Aug 2010, Walter Bright wrote:


 Jonathan M Davis wrote:

 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.


 
 True, but the idea of having a D style guide goes beyond just having a
 standard for Phobos. It fills a vacuum. When there is a reasonable existing
 one, lots of organizations will simply adopt it by default rather than go to
 the trouble of reinventing their own.


A good example of this is Java.  While I don't agree with the style -- it 
has a few things that _really_ annoy me -- it's followed by most 
developers.  Java code tends to look the same everywhere.  There's a huge 
value in this.

Python has achieved the same thing, even more so.  Partly based on baking 
structure into the syntax of the language.  Again, I don't agree with the 
style, but I do see the tremendous advantage in having strong consistency 
in the code base.

Later,
Brad
Aug 16 2010
prev sibling parent reply Kagamin <spam here.lot> writes:
bearophile Wrote:


 * In D, use of auto is recommended unless you want to make a
 specific point by mentioning the type.


 
 On the other hand code needs to be read too, sometimes by people that have not
written it. In this case seeing the actual types used is often better. So using
"auto" everywhere makes the code reading harder: if you aren't using an IDE
that tells you types, you sometimes need to follow the flux of the various
calls until you find what is the type, or sometimes you need to add temporary
writeln(typeof(x).stringof); inside the code to see what type it is. This
problem is common in dynamic languages.
 


I agree. Auto hinders understanding. Knowing that we have some fancy type here
gives you no knowledge about what's going on. Even with IDE. It also has issues
with interoperability. You don't want to pass fancy types to the external code,
do you?
It also contradicts with the intention to have uniform style because this is an
intention to have understandable code.
Aug 16 2010
parent dsimcha <dsimcha yahoo.com> writes:
== Quote from Kagamin (spam here.lot)'s article

 bearophile Wrote:

 * In D, use of auto is recommended unless you want to make a
 specific point by mentioning the type.


 On the other hand code needs to be read too, sometimes by people that have not




written it. In this case seeing the actual types used is often better. So using
"auto" everywhere makes the code reading harder: if you aren't using an IDE that
tells you types, you sometimes need to follow the flux of the various calls
until
you find what is the type, or sometimes you need to add temporary
writeln(typeof(x).stringof); inside the code to see what type it is. This
problem
is common in dynamic languages.


 I agree. Auto hinders understanding. Knowing that we have some fancy type here


gives you no knowledge about what's going on. Even with IDE. It also has issues
with interoperability. You don't want to pass fancy types to the external code,
do
you?

 It also contradicts with the intention to have uniform style because this is an


intention to have understandable code.

IMHO anyone who doesn't like auto is trying to write Java in D.  D is **NOT** a
purely nominative typing language because because use of templates in idiomatic
D,
especially D2, is so pervasive.  Even when I can't remember the type of
something
and need it, there's always typeof(), which is sometimes clearer as well.  For
example, I can never remember what type regex() returns, so:

class Foo {
    // Declare a regex as a member variable w/o ever explicitly
    // knowing its type.
    typeof(regex("", "")) myRegex;
}

Maybe it's just my bias of despising nominative typing but I believe that, when
programming, if you're thinking at the level of nominative types, you're usually
thinking at too low a level.



 Aug 17 2010