src/doc/style-guide/src/statements.md

   1 ### Let statements
   2
   3 There should be spaces after the `:` and on both sides of the `=` (if they are
   4 present). No space before the semi-colon.
   5
   6 ```rust
   7 // A comment.
   8 let pattern: Type = expr;
   9
  10 let pattern;
  11 let pattern: Type;
  12 let pattern = expr;
  13 ```
  14
  15 If possible the declaration should be formatted on a single line. If this is not
  16 possible, then try splitting after the `=`, if the declaration can fit on two
  17 lines. The expression should be block indented.
  18
  19 ```rust
  20 let pattern: Type =
  21     expr;
  22 ```
  23
  24 If the first line does not fit on a single line, then split after the colon,
  25 using block indentation. If the type covers multiple lines, even after line-
  26 breaking after the `:`, then the first line may be placed on the same line as
  27 the `:`, subject to the [combining rules](https://github.com/rust-lang-nursery/fmt-rfcs/issues/61) (WIP).
  28
  29
  30 ```rust
  31 let pattern:
  32     Type =
  33     expr;
  34 ```
  35
  36 e.g,
  37
  38 ```rust
  39 let Foo {
  40     f: abcd,
  41     g: qwer,
  42 }: Foo<Bar> =
  43     Foo { f, g };
  44
  45 let (abcd,
  46     defg):
  47     Baz =
  48 { ... }
  49 ```
  50
  51 If the expression covers multiple lines, if the first line of the expression
  52 fits in the remaining space, it stays on the same line as the `=`, the rest of the
  53 expression is not indented. If the first line does not fit, then it should start
  54 on the next lines, and should be block indented. If the expression is a block
  55 and the type or pattern cover multiple lines, then the opening brace should be
  56 on a new line and not indented (this provides separation for the interior of the
  57 block from the type), otherwise the opening brace follows the `=`.
  58
  59 Examples:
  60
  61 ```rust
  62 let foo = Foo {
  63     f: abcd,
  64     g: qwer,
  65 };
  66
  67 let foo =
  68     ALongName {
  69         f: abcd,
  70         g: qwer,
  71     };
  72
  73 let foo: Type = {
  74     an_expression();
  75     ...
  76 };
  77
  78 let foo:
  79     ALongType =
  80 {
  81     an_expression();
  82     ...
  83 };
  84
  85 let Foo {
  86     f: abcd,
  87     g: qwer,
  88 }: Foo<Bar> = Foo {
  89     f: blimblimblim,
  90     g: blamblamblam,
  91 };
  92
  93 let Foo {
  94     f: abcd,
  95     g: qwer,
  96 }: Foo<Bar> = foo(
  97     blimblimblim,
  98     blamblamblam,
  99 );
 100 ```
 101
 102
 103 ### Macros in statement position
 104
 105 A macro use in statement position should use parentheses or square brackets as
 106 delimiters and should be terminated with a semi-colon. There should be no spaces
 107 between the name, `!`, the delimiters, or the `;`.
 108
 109 ```rust
 110 // A comment.
 111 a_macro!(...);
 112 ```
 113
 114
 115 ### Expressions in statement position
 116
 117 There should be no space between the expression and the semi-colon.
 118
 119 ```
 120 <expr>;
 121 ```
 122
 123 All expressions in statement position should be terminated with a semi-colon,
 124 unless they end with a block or are used as the value for a block.
 125
 126 E.g.,
 127
 128 ```rust
 129 {
 130     an_expression();
 131     expr_as_value()
 132 }
 133
 134 return foo();
 135
 136 loop {
 137     break;
 138 }
 139 ```
 140
 141 Use a semi-colon where an expression has void type, even if it could be
 142 propagated. E.g.,
 143
 144 ```rust
 145 fn foo() { ... }
 146
 147 fn bar() {
 148     foo();
 149 }
 150 ```