Difference between revisions of "Phobos and Druntime Style Guide"

From D Wiki
Jump to: navigation, search
(Whitespace)
(Language Features: Category:Contribution_Guidelines)
 
(6 intermediate revisions by 3 users not shown)
Line 64: Line 64:
 
* Always insert a space after <tt>,</tt> (comma) except when comma is last in line.
 
* Always insert a space after <tt>,</tt> (comma) except when comma is last in line.
 
* Always insert either a space or a newline after <tt>;</tt> (semicolon).
 
* Always insert either a space or a newline after <tt>;</tt> (semicolon).
 +
 +
= Comments =
 +
 +
Use:
 +
 +
<syntaxhighlight lang="D">
 +
/***
 +
Ddoc comment
 +
more than one line long
 +
*/
 +
</syntaxhighlight>
 +
 +
for multiline Ddoc comments, not <tt>/++ +/</tt> or <tt>///</tt> comments.
  
 
= Naming =
 
= Naming =
Line 72: Line 85:
 
* 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> so no need to parenthesize <tt>a && b || c</tt>.
 +
* You may assume it's understood <tt></tt> and <tt></tt> have precedence over <tt></tt> and <tt></tt>, so no need to parenthesize around <tt>a + b * c</tt>.
 +
* You may assume it's understood <tt>==</tt>, <tt>!=</tt>, <tt><</tt>, <tt><=</tt>, <tt>></tt>, <tt>>=</tt> have lower precedence than <tt>+</tt>, <tt>-</tt>, <tt>*</tt>, <tt>/</tt>, <tt>%</tt>, so no need to parenthesize around <tt>a + b < c * d</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 =
 +
 +
* Sort <tt>import</tt>s alphabetically, whether they're grouped in the same <tt>import</tt> statement or one per <tt>import</tt> statement.
 +
 +
[[Category:Contribution_Guidelines]]

Latest revision as of 11:52, 21 September 2018

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

Comments

Use:

/***
Ddoc comment
more than one line long
*/

for multiline Ddoc comments, not /++ +/ or /// comments.

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 || so no need to parenthesize a && b || c.
  • You may assume it's understood and have precedence over and , so no need to parenthesize around a + b * c.
  • You may assume it's understood ==, !=, <, <=, >, >= have lower precedence than +, -, *, /, %, so no need to parenthesize around a + b < c * d.
  • 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.