3 ms·
The issue I think is that the documentation which is separated from code can easily go out of sync with the actual code, so it's worth to make writing documenta
by xyzzyz 11y ago
The issue I think is that the documentation which is separated from code can easily go out of sync with the actual code, so it's worth to make writing documentation alongside the code as easy as possible, while trying not to obscure the code itself too much.
- acveilleux 11y agoI'd argue that for public APIs (defined as API users don't site next to/are the same as the API devs) this concern with "getting out of date" is moot compared to the benefit of detailed docs. If anything, it's the API signatures that get out of sync with the user's needs. And as anyone who's ever tried to deprecate public APIs will know, it's a real pain, frustrating to users and devs alike.
- shawn-butler 11y agoWhenever I see this comment I can't resist urge to make reference to Knuth: https://en.wikipedia.org/wiki/Literate_programming https://en.wikipedia.org/wiki/Literate_programming No language developer ever seems to take it seriously as a design challenge to solve though. You get tools like rustdoc as "good enough"