3 ms·
> A piece of code with a design document at least has a historical record of what the original aims of the project were, and a written rationale for why they to
by fdsfsaa 10y ago
> A piece of code with a design document at least has a historical record of what the original aims of the project were, and a written rationale for why they took certain approaches.
That information is very useful, particularly as a comment or a commit message. Storing this information in a separate unversioned document off on some enterprise management system makes it harder to find. If you put the rationale for a change in the commit message, the rationale is right there when you run blame!
- vertex-four 10y agoAnd what about when your commit is part of a 5-patch series, as part of a 3-series project to bring some internal framework code up to scratch in order to start implementing a new feature? Which commit do you stick your design rationale on, and how do you ensure people will see it? Commit messages are really good for e.g. "patch that due to this bug" or "refactor this so it's decoupled from that feature", but not quite so good for describing arches in development. On the other hand, you can reference an issue in every commit message, and that issue can lead to the design document.