hphp/hack/src/style_guide.md

   1 Style Guide
   2 ===========
   3
   4 As far as indentation rules go, ocp-indent should be used as the final word.
   5
   6 However, here are some examples.
   7
   8 Let Expressions
   9 ---------------
  10
  11 Try to fit a `let ... in` onto one line:
  12
  13     let foo = bar x y z in
  14     ...
  15
  16 If the expression is too long, first try
  17
  18     let foo =
  19       some_long_expression_bar x y z in
  20       ...
  21
  22 If the second line is still too long, fall back to
  23
  24     let foo =
  25       some_long_expression_bar
  26         long_arg_1
  27         long_arg_2
  28         long_arg_3 in
  29
  30 Match Clauses
  31 -------------
  32
  33 Don't indent the clauses of a standalone match expression
  34
  35     match foo with
  36     | Some x -> ...
  37     | None -> ...
  38
  39 However, if the match expression is the RHS of a let expression, do indent them:
  40
  41     let bar = match foo with
  42       | Some x -> ...
  43       | None -> ...
  44     in
  45     ...
  46
  47 Alternatively, if `foo` is too long, move the `match` to the next line:
  48
  49     let foo =
  50       match some_long_expression arg1 arg2 with
  51       | Some x -> ...
  52       | None -> ...
  53     in
  54     ...
  55
  56 If the expression between `match ... with` is too long to fit into one line,
  57 split it out as in separate `let` expression. That is, instead of
  58
  59     let foo = match some_long_expression
  60       arg1 arg2 with
  61       | Some x -> ...
  62       | None -> ...
  63     in
  64     ...
  65
  66 Prefer
  67
  68     let bar = some_long_expression arg1 arg2 in
  69     let foo = match  bar with
  70       | Some x -> ...
  71       | None -> ...
  72     in
  73     ...
  74
  75 Note that the `in` should be on its own line. I.e. avoid
  76
  77     let bar = match foo with
  78       | Some x -> ...
  79       | None -> ...  in
  80     ...
  81
  82 Functions
  83 ---------
  84
  85 Function expressions that span multiple lines should be wrapped in a `begin ...  end`:
  86
  87     List.iter foo begin fun x ->
  88       ...
  89     end
  90
  91 However, expressions on a single line should use parentheses:
  92
  93     List.map foo (fun x -> x + 1)
  94
  95 In general, function bodies should be indented. However, we make an exception
  96 if `fun` comes right after an operator (typically one of `>>=`, `@@`, or `>>|`):
  97
  98     some_monadic_x >>= fun x ->
  99     some_monadic_y >>= fun y ->
 100     return x + y
 101
 102 Modules
 103 -------
 104
 105 Top-level modules (those created by individual files) should be named using
 106 Underscore_separated_words. Modules within files should be CamelCase.
 107
 108 Top-level module opens should be reserved only for very commonly used modules,
 109 like `Utils`. Aside from those, prefer
 110
 111     module LMN = Long_module_name
 112
 113 or use local opens:
 114
 115     let open Long_module_name in
 116     ...
 117
 118 Modules should have the name of their containing directory as a prefix. E.g.
 119 modules under typing/ should be named as `Typing_foo`.
 120
 121 Parentheses
 122 -----------
 123
 124 Generally, there are only two cases where parentheses / `begin ... end` are
 125 necessary: for nesting `with` clauses and for inserting multiple
 126 semicolon-separated expressions into the `then` clause of an `if`-expression.
 127
 128     match foo with
 129     | Some x ->
 130       begin match bar with
 131        | Some y -> ...
 132        | None -> ...
 133       end
 134     | None -> ...
 135
 136     if foo then begin
 137       do_something ();
 138       do_another_thing ();
 139     end
 140
 141 If the test expression is too long, the following is also acceptable:
 142
 143     if long_expression arg1 arg2
 144     then begin
 145       do_something ();
 146       do_another_thing ();
 147     end
 148
 149 Variants
 150 --------
 151
 152 Variants should be named using `Capitalized_underscore_separated_words`.
 153
 154 This includes polymorphic variants; i.e. we want `\`Foo` and not `\`foo`. In
 155 fact, the OCaml manual suggests that lowercase polymorphic variants may be
 156 deprecated in future versions.
 157
 158 Miscellany
 159 ----------
 160
 161 Boolean function parameters should always be labeled. Consider labeling
 162 integer parameters as well.
 163
 164 Try to use exhaustive matching whenever possible. That is, avoid the wildcard
 165 `_` match.