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 disadvantages of 'auto' in C++0x and 'var' in C#. I like the D 'auto' and I use 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 disadvantages of 'auto' in C++0x and 'var' in C#. I like the D 'auto' and I use 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
next sibling parent 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. Few discussions regarding the 'var' of C#: 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
prev sibling next sibling parent 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
prev sibling 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.

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.

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
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 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
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 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 next sibling parent 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
prev sibling parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
--001485e5c09cca3482048dfb32a2
Content-Type: text/plain; charset=ISO-8859-1

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

--001485e5c09cca3482048dfb32a2 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable I think Jonathan was talking about the entire community, not a single proje= ct. It&#39;s impossible for all people to accept a unified standard, everyo= ne has their own style and they&#39;ll most probably keep it that way. What= matters is consistency. So if you have a certain way of coding, be consist= ent about it throughout your project.<br> <br><div class=3D"gmail_quote">On Tue, Aug 17, 2010 at 3:38 AM, bearophile = <span dir=3D"ltr">&lt;<a href=3D"mailto:bearophileHUGS lycos.com">bearophil= eHUGS lycos.com</a>&gt;</span> wrote:<br><blockquote class=3D"gmail_quote" = style=3D"margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 20= 4); padding-left: 1ex;"> Jonathan M Davis:<br> <div class=3D"im"><br> &gt; I see little no value in trying to enforce any kind of<br> &gt; coding standard on the D community as a whole,<br> <br> </div>If your program is partially composed by several modules written by d= ifferent programmers, that you have found on the net (like from dsource), y= ou will not appreciate to see your program as an Harlequin written in ten w= idely different coding styles. A more uniform coding style helps you see yo= ur 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&#39;t see the advantage o= f this for your D/Python programs then maybe it&#39;s because you haven&#39= ;t done this yet :-)<br> <br> Bye,<br> <font color=3D"#888888">bearophile<br> </font></blockquote></div><br> --001485e5c09cca3482048dfb32a2--
Aug 16 2010