... | @@ -199,6 +199,14 @@ Another is `Note [Quasi-quote overview]` in `Language.Haskell.Syntax.Expr`. |
... | @@ -199,6 +199,14 @@ 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
|
|
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.
|
|
summarises the overall design. An overview makes the MR much easier to review.
|
|
|
|
|
|
|
|
### 2.3 The past and the present
|
|
|
|
|
|
|
|
**A commit messages describes a *change*; a comment or a Notes describe 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.
|
|
|
|
|
|
## 3. Tickets, merge requests, and commits
|
|
## 3. Tickets, merge requests, and commits
|
|
|
|
|
... | | ... | |