... | ... | @@ -199,14 +199,42 @@ Another is `Note [Quasi-quote overview]` in `Language.Haskell.Syntax.Expr`. |
|
|
Many (not all) MRs would be strengthened by adding a suitable overview Note, that
|
|
|
summarises the overall design. An overview makes the MR much easier to review.
|
|
|
|
|
|
### 2.3 Notes describe the present state, not the journey
|
|
|
### 2.3 Being specific, using examples
|
|
|
|
|
|
* Be specific. Don't just say "we reject overlapping instances in situation X". Instead point directly to the code that implements that decision.
|
|
|
* Offer concrete examples to illustrate the point. It can be fantastically illuminating to see how some general point plays out in a particular example.
|
|
|
* Mention specific tickets and/or testsuite cases that further illustrate the issue.
|
|
|
|
|
|
Here's an example
|
|
|
```
|
|
|
Note [Put touchable variables on the left]
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
Ticket #10009, a very nasty example:
|
|
|
|
|
|
f :: (UnF (F b) ~ b) => F b -> ()
|
|
|
|
|
|
g :: forall a. (UnF (F a) ~ a) => a -> ()
|
|
|
g _ = f (undefined :: F a)
|
|
|
|
|
|
For g we get [G] g1 : UnF (F a) ~ a
|
|
|
[W] w1 : UnF (F beta) ~ beta
|
|
|
[W] w2 : F a ~ F beta
|
|
|
|
|
|
g1 is canonical (CEqCan). It is oriented as above because a is not touchable.
|
|
|
See canEqTyVarFunEq.
|
|
|
```
|
|
|
Notice the concrete example, the pointer to #10009, and the pointer to `canEqTyVarFunEq`.
|
|
|
|
|
|
Caution: it is easy for these code references to get out of date. But that's a lesser evil.
|
|
|
|
|
|
### 2.4 Notes describe the present state, not the journey
|
|
|
|
|
|
**A commit message describes a *change*; a comment or a Note describes a *state*.**. That is, a Note or a comment should always describe the current state of affairs, not the journey that led to that state of affairs.
|
|
|
At the moment you write it, the journey is high in your consciousness; but in ten years time, it is at best a distraction, and at worst the Note becomes simply incomprehensible without knowledge of the
|
|
|
previous state of affairs.
|
|
|
|
|
|
Exception: sometimes it can be helpful to have a clearly-signposted section called "Historical note: blah blah" that describes some previous state of affairs.
|
|
|
But the "Historical note" signpost signals that you don't need to read it to understand the current compiler.
|
|
|
* **Design choices**. A Note can be a good place to document the reasoning that led to a particular decision. Lacking the reasoning, someone might change the decision later, without realising the consequences.
|
|
|
* **Historical notes**. Sometimes it can be helpful to have a clearly-signposted section called "Historical note: blah blah" that describes some previous state of affairs. But the "Historical note" signpost signals that you don't need to read it to understand the current compiler.
|
|
|
|
|
|
## 3. Tickets, merge requests, and commits
|
|
|
|
... | ... | |