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

   1 # Guiding principles and rationale
   2
   3 When deciding on style guidelines, the style team tried to be guided by the
   4 following principles (in rough priority order):
   5
   6 * readability
   7     - scan-ability
   8     - avoiding misleading formatting
   9     - accessibility - readable and editable by users using the the widest
  10       variety of hardware, including non-visual accessibility interfaces
  11     - readability of code when quoted in rustc error messages
  12
  13 * aesthetics
  14     - sense of 'beauty'
  15     - consistent with other languages/tools
  16
  17 * specifics
  18     - compatibility with version control practices - preserving diffs,
  19       merge-friendliness, etc.
  20     - preventing right-ward drift
  21     - minimising vertical space
  22
  23 * application
  24     - ease of manual application
  25     - ease of implementation (in Rustfmt, and in other tools/editors/code generators)
  26     - internal consistency
  27     - simplicity of formatting rules
  28
  29
  30 ## Overarching guidelines
  31
  32 Prefer block indent over visual indent. E.g.,
  33
  34 ```rust
  35 // Block indent
  36 a_function_call(
  37     foo,
  38     bar,
  39 );
  40
  41 // Visual indent
  42 a_function_call(foo,
  43                 bar);
  44 ```
  45
  46 This makes for smaller diffs (e.g., if `a_function_call` is renamed in the above
  47 example) and less rightward drift.
  48
  49 Lists should have a trailing comma when followed by a newline, see the block
  50 indent example above. This choice makes moving code (e.g., by copy and paste)
  51 easier and makes smaller diffs.