Comment by tln
15 hours ago
Extracting unit tests from your docs: great!
Somehow extracting your docs from unit tests: might be ok!
Pointing people at unit tests instead of writing docs: not even remotely ok.
Is that really what this guy is advocating??
> Pointing people at unit tests instead of writing docs: not even remotely ok.
Couldn't agree more
I'm trying to integrate with a team at work that is doing this, and I'm finding it impossible to get a full picture of what their service can do.
I've brought it up with my boss, their boss, nothing happens
And then the person writing the service is angry that everyone is asking him questions about it all the time. "Just go read the tests! You'll see what it does if you read the tests!"
Incredibly frustrating to deal with when my questions are about the business rules for the service, not the functionality of the service
The code, tests and comments convey what actual business rules are implemented.
While documentation is someone's non-precise natural language expression of what (to the best of their imperfect human capacity) expected the code to implement at the time of writing.
Yes, it is absolutely more valuable to know what the code "should" be doing than to know what the code is doing
Otherwise there is no way to know what is expected behavior or just a mistake built into it by accident
1 reply →
"Oh yeah, those tests are always flaky. We just rerun them until they pass. Or we turn them off. I mean, Jeff wrote them like three years ago and he quit last year, so..."
I'd rather have the prose. And if it's wrong, then fix it. I'm so tired of these excuses.
No, not replacing documentation is a way to enrich documentation. That being said, that should have been clearer; I will update it.
Thanks, "This guy"