remote/doc/CodeStyle.md

   1 # Style guide
   2
   3 Like other projects, we also have some guidelines to keep to the code.
   4 For the overall Remote Agent project, a few rough rules are:
   5
   6 * Make your code readable and sensible, and don’t try to be clever.
   7   Prefer simple and easy solutions over more convoluted and foreign syntax.
   8
   9 * Fixing style violations whilst working on a real change as a preparatory
  10   clean-up step is good, but otherwise avoid useless code churn for the sake
  11   of conforming to the style guide.
  12
  13 * Code is mutable and not written in stone.  Nothing that is checked in is
  14   sacred and we encourage change to make this a pleasant ecosystem to work in.
  15
  16 * We never land any code that is unnecessary or unused.
  17
  18 ## Documentation
  19
  20 We keep our documentation (what you are reading right now!) in-tree
  21 under [remote/doc].  Updates and minor changes to documentation should
  22 ideally not be scrutinized to the same degree as code changes to
  23 encourage frequent updates so that documentation does not go stale.
  24 To that end, documentation changes with `r=me a=doc` from anyone
  25 with commit access level 3 are permitted.
  26
  27 Use fmt(1) or an equivalent editor specific mechanism (such as
  28 `Meta-Q` in Emacs) to format paragraphs at a maximum of
  29 75 columns with a goal of roughly 65.  This is equivalent to `fmt
  30 -w75 -g65`, which happens to the default on BSD and macOS.
  31
  32 The documentation can be built locally this way:
  33
  34 ```shell
  35 % ./mach doc remote
  36 ```
  37
  38 [remote/doc]: https://searchfox.org/mozilla-central/source/remote/doc
  39
  40 ## Linting
  41
  42 The Remote Agent consists mostly of JavaScript code, and we lint that
  43 using [mozlint], which is harmonizes different linters including [eslint].
  44
  45 To run the linter and get sensible output for modified files:
  46
  47 ```shell
  48 % ./mach lint --outgoing --warning
  49 ```
  50
  51 For certain classes of style violations, eslint has an automatic
  52 mode for fixing and formatting code.  This is particularly useful
  53 to keep to whitespace and indentation rules:
  54
  55 ```shell
  56 % ./mach lint --outgoing --warning --fix
  57 ```
  58
  59 The linter is also run as a try job (shorthand `ES`) which means
  60 any style violations will automatically block a patch from landing
  61 (if using autoland) or cause your changeset to be backed out (if
  62 landing directly on inbound).
  63
  64 If you use git(1) you can [enable automatic linting] before
  65 you push to a remote through a pre-push (or pre-commit) hook.
  66 This will run the linters on the changed files before a push and
  67 abort if there are any problems.  This is convenient for avoiding
  68 a try run failing due to a simple linting issue.
  69
  70 [mozlint]: /code-quality/lint/mozlint.rst
  71 [eslint]: /code-quality/lint/linters/eslint.rst
  72 [enable automatic linting]: /code-quality/lint/usage.rst#using-a-vcs-hook