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 in contexts without syntax highlighting or IDE
  12       assistance, such as rustc error messages, diffs, grep, and other
  13       plain-text contexts
  14
  15 * aesthetics
  16     - sense of 'beauty'
  17     - consistent with other languages/tools
  18
  19 * specifics
  20     - compatibility with version control practices - preserving diffs,
  21       merge-friendliness, etc.
  22     - preventing right-ward drift
  23     - minimising vertical space
  24
  25 * application
  26     - ease of manual application
  27     - ease of implementation (in Rustfmt, and in other tools/editors/code generators)
  28     - internal consistency
  29     - simplicity of formatting rules
  30
  31
  32 ## Overarching guidelines
  33
  34 Prefer block indent over visual indent. E.g.,
  35
  36 ```rust
  37 // Block indent
  38 a_function_call(
  39     foo,
  40     bar,
  41 );
  42
  43 // Visual indent
  44 a_function_call(foo,
  45                 bar);
  46 ```
  47
  48 This makes for smaller diffs (e.g., if `a_function_call` is renamed in the above
  49 example) and less rightward drift.
  50
  51 Lists should have a trailing comma when followed by a newline, see the block
  52 indent example above. This choice makes moving code (e.g., by copy and paste)
  53 easier and makes smaller diffs.