www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - D style guide

reply Joseph Rushton Wakeling <joseph.wakeling webdrake.net> writes:
Hi all,

A recent Phobos pull request got critiqued over some stylistic aspects -- which
was obviously disappointing as I thought I'd learned those guidelines fairly
well.

Just to make sure, are the rules at http://dlang.org/dstyle.html considered to
be the ones to follow -- and up to date?  There are no extra guidelines
available elsewhere (e.g. on the wiki)?

I ask because several of the rules that I was requested to follow are not listed
there:

   * Space after if -- e.g. if (x < 0) not if(x < 0).  This isn't cited, and in
     fact the example given (at the end of the page) has no space after if.
     Also, what about other statements such as while, for, foreach, etc.?

   * Full bracing.  It's mentioned that opening braces should be on their own
     line, but not that braces should be used even in the case of single-line
     statements, i.e. that one should do,

         if (x < 0)
         {
             negative = true;
         }
         else
         {
             negative = false;
         }

     and not

         if (x < 0)
             negative = true;
         else
             negative = false;

     I have a memory of being instructed specifically _not_ to use bracing for
     single-line statements at the time I submitted my first ever pull request,
     but I may be mistaken.

   * Use of brackets around sides of a conditional, e.g. to write

         if (x + y < w * z)

     and not

         if ((x + y) < (w * z))

So, have I missed something in a style guide in a different location, or have
these rules simply been adopted by custom without making it into official
guidelines?  If the latter, should I make a pull request for the website? :-)

I'd also appreciate guidelines about template if statements and indentation: is
it preferred to write e.g.

    auto func(R)(R input)
        if(isInputRange!R)
    {
        ...
    }

or,

    auto func(R)(R input)
    if(isInputRange!R)
    {
        ...
    }

I see both in Phobos.  I must say I prefer the former, as it somehow highlights
the presence of the 'if' statement and its connection to function declaration
and body, but is there an official view?

Same for in/out contracts: is it preferred to have,

    auto func(...)
        in
        {
            ...
        }
        out
        {
            ...
        }
    body
    {
        ...
    }

... or all on the same indentation level?  (Again, I personally prefer the
indentation of the in/out blocks.)

Thanks & best wishes,

    -- Joe
Jun 17 2013
parent reply =?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
Please ignore my comments because they are bike-shedding. I am not sure 
about Phobos coding guidelines.

On 06/17/2013 09:13 AM, Joseph Rushton Wakeling wrote:

     * Space after if -- e.g. if (x < 0) not if(x < 0).  This isn't 
cited, and in
       fact the example given (at the end of the page) has no space 
after if.
       Also, what about other statements such as while, for, foreach, 
etc.? I want that space. It is very common in most C++ guidelines as well.
     * Full bracing.  It's mentioned that opening braces should be on 
their own
       line, but not that braces should be used even in the case of 
single-line
       statements, i.e. that one should do,

           if (x < 0)
           {
               negative = true;
           }
           else
           {
               negative = false;
           }

       and not

           if (x < 0)
               negative = true;
           else
               negative = false;
Yes, curly brackets are very helpful in readability even when there is no reason.
     * Use of brackets around sides of a conditional, e.g. to write

           if (x + y < w * z)

       and not

           if ((x + y) < (w * z))
I am on the other side on that one: Use parentheses to show intent even when unnecessary.
 I'd also appreciate guidelines about template if statements and 
indentation: is
 it preferred to write e.g.

      auto func(R)(R input)
          if(isInputRange!R)
      {
          ...
      }

 or,

      auto func(R)(R input)
      if(isInputRange!R)
      {
          ...
      }

 I see both in Phobos.  I must say I prefer the former, as it somehow 
highlights
 the presence of the 'if' statement
Me too: Indentation helps with readability.
 Same for in/out contracts: is it preferred to have,

      auto func(...)
          in
          {
              ...
          }
          out
          {
              ...
          }
      body
      {
          ...
      }

 ... or all on the same indentation level?  (Again, I personally 
prefer the
 indentation of the in/out blocks.)
I don't like that indentation. I know that Phobos wants the opening curly bracket on its own and that's what I am used to elsewhere, but I have gotten used to seeing it at the end of the previous line. Except, I still don't like it for functions (member or regular), structs, classes, version, etc. I think I like it only after control-flow keywords like if, foreach, while, etc. But if we go with others' preference, then I have seen code like this: auto func(...) in { ... } out { ... } body { ... } Getting back to your question: I don't know. :p Ali
Jun 17 2013
parent reply Joseph Rushton Wakeling <joseph.wakeling webdrake.net> writes:
On 06/17/2013 05:36 PM, Ali Çehreli wrote:
 I want that space. It is very common in most C++ guidelines as well.
Any particular reason? It's not something that had ever occurred to me as being important one way or the other.
 Yes, curly brackets are very helpful in readability even when there is no
reason.
Is also useful functionally, as it avoids the problem of someone accidentally forgetting to add braces when they add an extra line inside the scope.
 I am on the other side on that one: Use parentheses to show intent even when
 unnecessary.
Me too, although in my case it was also unfounded paranoia about operator precedence ...
 Same for in/out contracts: is it preferred to have,

      auto func(...)
          in
          {
              ...
          }
          out
          {
              ...
          }
      body
      {
          ...
      }

 ... or all on the same indentation level?  (Again, I personally prefer the
 indentation of the in/out blocks.)
I don't like that indentation.
I came to it by accident, as it was the default way in which my editor chose to indent when I started typing 'in', but I do rather like the way in which it highlights the contracts as distinct from the function declaration and body. But it's not something I feel strongly about.
 I know that Phobos wants the opening curly bracket on its own and that's what I
 am used to elsewhere, but I have gotten used to seeing it at the end of the
 previous line. Except, I still don't like it for functions (member or regular),
 structs, classes, version, etc. I think I like it only after control-flow
 keywords like if, foreach, while, etc.
I found myself rather liking the spec Linus Torvalds gave for the Linux kernel, which was: separate-line opening brace for functions, same-line for control statements (if, while, etc.). It's what I've tended to use for my own D code, although I'm considering that it might be best to go with strict Phobos style just in order to help with uniformity of D style.
 But if we go with others' preference, then I have seen code like this:
 
 auto func(...)
 in {
     ...
 
 } out {
     ...
 
 } body {
     ...
 }
I _really_ don't like that, although I can see why someone would come up with it. It just clashes so horribly with both Phobos style and with the Linus-style "separate line opening brace for functions" which I'm so used to using. (Though I've never contributed to the kernel!).
Jun 17 2013
parent reply =?UTF-8?B?QWxpIMOHZWhyZWxp?= <acehreli yahoo.com> writes:
On 06/17/2013 12:09 PM, Joseph Rushton Wakeling wrote:

 On 06/17/2013 05:36 PM, Ali Çehreli wrote:
 I want that space. It is very common in most C++ guidelines as well.
Any particular reason? It's not something that had ever occurred to
me as being
 important one way or the other.
I have no idea why that style have evolved but I like it. :) The reason may be to distinguish from function calls: foo(expr) if (expr) I can't think anything else. Ali
Jun 17 2013
next sibling parent "H. S. Teoh" <hsteoh quickfur.ath.cx> writes:
On Mon, Jun 17, 2013 at 12:58:08PM -0700, Ali ehreli wrote:
 On 06/17/2013 12:09 PM, Joseph Rushton Wakeling wrote:
 
 On 06/17/2013 05:36 PM, Ali ehreli wrote:
 I want that space. It is very common in most C++ guidelines as well.
Any particular reason? It's not something that had ever occurred
to me as being
 important one way or the other.
I have no idea why that style have evolved but I like it. :) The reason may be to distinguish from function calls: foo(expr) if (expr) I can't think anything else.
[...] Yeah, I find this distinction very helpful in distinguishing between a function call and a built-in construct. Writing if(expr) without a space just *feels* wrong. One thing that *may* change my mind is in the unlikely event that D adopts the (arguably questionable) convention of allowing a delegate final argument to be placed outside of the closing parenthesis, i.e.: func(expr) { doSomething(); } is equivalent to: func(expr, { doSomething(); }); And: func(var; expr) { doSomething(var); } is equivalent to: func(expr, (var) { doSomething(var); }); But I'm not sure this idea will ever fly, so for now, my stance is to always use a space after "if". :-) T -- Prosperity breeds contempt, and poverty breeds consent. -- Suck.com
Jun 17 2013
prev sibling next sibling parent Joseph Rushton Wakeling <joseph.wakeling webdrake.net> writes:
On 06/17/2013 08:58 PM, Ali Çehreli wrote:
 I have no idea why that style have evolved but I like it. :) The reason may be
 to distinguish from function calls:
 
     foo(expr)
 
     if (expr)
 
 I can't think anything else.
Makes sense to me, and I do like these kinds of visual distinction. :-)
Jun 17 2013
prev sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Monday, June 17, 2013 21:14:15 Joseph Rushton Wakeling wrote:
 On 06/17/2013 08:58 PM, Ali Çehreli wrote:
 I have no idea why that style have evolved but I like it. :) The reason
 may be> 
 to distinguish from function calls:
 foo(expr)
 
 if (expr)
 
 I can't think anything else.
Makes sense to me, and I do like these kinds of visual distinction. :-)
Whereas, they make no sense to me. if is a keyword, so the difference is quite clear, and IMHO the space adds useless, visual noise. But code formatting is an area where reasonable people frequently disagree. - Jonathan M Davis
Jun 17 2013