... | ... | @@ -199,9 +199,9 @@ 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 The past and the present
|
|
|
### 2.3 Notes describe the present state, not the journey
|
|
|
|
|
|
**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.
|
|
|
**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.
|
|
|
|
... | ... | |