Re:The Surprising Power of Documentation
by kristiandupont on Monday June 12, 2023 @06:26AM
(#36291185)
It's true that there can be gotcha's in code which should be documented, but I don't think forcing a template on people is the solution. In fact, I wouldn't expect people to be better at documenting them with that in place.
[ Parent
| on HN ]
Well, yes, you need to have manual or automatic checks for the presence of the template, and the correctness of the contents is often uncheckable by automated tests. But if things break and e.g. the filled-in documentation template incorrectly said "thread-safe: yes", it will be very easy to 'git blame' the culprit. That way you can at least slowly weed out the sloppy documenters, but I admit that this is tedious.
And, yes, I don't like this either and would like a better solution. But so far I didn't get any viable suggestions.