[andrewfong]

That's a good way to prevent regressions but it's not the same thing as documentation or a mental model.

The tests tell you what it's supposed to do, not how it does it.

[spankalee]

Or _why_

[dllthomas]

For a while now I've been dreaming about a system that lets me link tests to documentation. In a similar way that citations of other documents support claims in many domains, claims about software could be backed up by tests that demonstrate the claim. Then, when a test fails, the system could surface the relevant pieces of documentation (whether they're developer facing or user facing) so the developer knows the _why_ they're trying to preserve as they update some combination of the code, the test, and the documentation.

[andrewfong]

I'd guess you could get pretty far by just adding comments with links to product specs, JIRA tickets, or Slack/chat threads, as applicable.

[Izkata]

That's what the commit message that added that test is for. And an example of why I'm strongly against squashing commits.