Difference between revisions of "Phobos and Druntime Style Guide"

From D Wiki
Jump to: navigation, search
(Naming)
(Language Features)
Line 72: Line 72:
 
* When a symbol may refer to a type and also a value, use the convention for values.
 
* When a symbol may refer to a type and also a value, use the convention for values.
 
* Generally avoid <tt>CAPS</tt> names even when abbreviations.
 
* Generally avoid <tt>CAPS</tt> names even when abbreviations.
 +
 +
= Parenthesizing =
 +
 +
* Do not parenthesize single template arguments, i.e. use <tt>isInputRange!Range</tt> not <tt>isInputRange!(Range)</tt>.
 +
* Do not parenthesize the argument in single-argument lambdas, i.e. use <tt>a => a + 1</tt> not <tt>(a) => a + 1</tt>.
 +
* You may assume it's understood <tt>&&</tt> has precedence over <tt>||</tt>, and both have lower precedence than <tt>==</tt>, <tt>!=</tt>, <tt><</tt>, <tt><=</tt>, <tt>></tt>, <tt>>=</tt>. Everything else should be parenthesized in expressions.
 +
* Do not parenthesize <tt>return</tt> expressions, i.e. use <tt>return a + b;</tt> not <tt>return (a + b);</tt>
  
 
= Language Features =
 
= Language Features =
  
 
* Sort <tt>import</tt>s alphabetically, whether they're grouped in the same <tt>import</tt> statement or one per <tt>import</tt> statement.
 
* Sort <tt>import</tt>s alphabetically, whether they're grouped in the same <tt>import</tt> statement or one per <tt>import</tt> statement.

Revision as of 13:52, 15 January 2016

Many people have contributed to the core D library Druntime and the standard D library Phobos. Over the years, the codebases have accumulated a mix of styles. Whilst each particular style is entirely fine on its own, code containing a mishmash of styles is jarring. This document sets out a number of style guidelines that all new Phobos code should follow. The plan going forward is to automate these simple rules for new pull requests and later for the entire codebase.

Indentation and Bracing

  • Indentation level is four spaces.
  • There is no fraction of an indent. All indentation is a multiple of 4 spaces.
  • Elaborate vertical alignment (i.e. tabulation) is to be avoided.
  • Multiple indent shall occur under specific circumstances enumerated later in this document.
  • When present on their own line, template constraints are not indented extra. Example:
int fun(T)(T value)
if (isIntegral!T)
{
    ...
}
  • Opening and closing braces for scopes and static if shall be on their own line. There is no other code on lines with such braces.
  • In contract code, in, out, body are not indented. Example:
int fun(T)(T value)
if (isIntegral!T)
in
{
    ...
}
out
{
    ...
}
body
{
    ...
}
  • Long conditions inside the parens of for, foreach, foreach_reverse, if, switch, while, with shall be multiply indented proportionally to the depth of parentheses used. Connecting operators shall be at the end of the line. Example:
if (one_very_very_super_extremely_long_condition &&
    another_very_very_super_extremely_long_condition &&
    (parenthesized_very_very_super_extremely_long_condition || 
        extra_indented_because_of_parens_condition))
{
    ...
}

Whitespace

  • No whitespace at end of line.
  • Use empty lines in functions sparingly. If too many, that's a sign the function is too long.
  • There shall not be two or more blank lines in any module.
  • An open paren cannot be followed by a space.
  • A closed paren cannot be preceded by a space.
  • Always insert a space (except if at the end of line) after the following: catch, do, else, enum, finally, for, foreach, foreach_reverse, if, in, is, return, switch, throw, try, while, with.
  • Always insert a space around all binary operators.
  • Always insert spaces around .. (double dot).
  • Never insert a space between a unary operator and its argument.
  • No space after function name in a function call.
  • No space after cast, space after the closing paren in a cast expression. Example: cast(int) x.
  • Always insert a space after , (comma) except when comma is last in line.
  • Always insert either a space or a newline after ; (semicolon).

Naming

  • Module names are as_shown_here: valid D symbols containing only lowercase letters, digits, and underscores.
  • Value names are asShownHere.
  • Type and tempalte names are AsShownHere.
  • When a symbol may refer to a type and also a value, use the convention for values.
  • Generally avoid CAPS names even when abbreviations.

Parenthesizing

  • Do not parenthesize single template arguments, i.e. use isInputRange!Range not isInputRange!(Range).
  • Do not parenthesize the argument in single-argument lambdas, i.e. use a => a + 1 not (a) => a + 1.
  • You may assume it's understood && has precedence over ||, and both have lower precedence than ==, !=, <, <=, >, >=. Everything else should be parenthesized in expressions.
  • Do not parenthesize return expressions, i.e. use return a + b; not return (a + b);

Language Features

  • Sort imports alphabetically, whether they're grouped in the same import statement or one per import statement.