4 ms·
That's a very good habit to be in, however when it comes to external-facing stuff, e.g. APIs, or stuff that needs a lot more detail (and especially examples) th
by barnacled 6y ago
That's a very good habit to be in, however when it comes to external-facing stuff, e.g. APIs, or stuff that needs a lot more detail (and especially examples) then you're going to need more than self-documenting code.
Of course getting out of sync is a real massive issue and a total pain. But that's another reason for people to contribute to such things :)
- opportune 6y agoFor APIs, there are tools to parse out comments (that the linter requires) into the API description. Doesn't give examples or much of a "when to use this" usually, but I've found it's better than nothing. For me personally, even though I dislike these auto-generated docs since they're quite terse (and tend to display niche parts of the API just as prominently as the parts you likely want to use), I tend to find them much more reliable than more detailed guides precisely because they tend not to desync, so I often don't even bother with well-written guides anymore, since they are much more likely to waste my time (or at least be inaccurate). I'd expect many other developers have the same level of trust issues I do, to the point that those shitty auto-generated docs are in some ways better than really nice, detailed docs, because they are easier to trust. I'm unlikely to break the habit of ignoring detailed docs/guides unless it's coming from some big project where they're uniformly good. Otherwise, reading them tends to be a waste of time IMO.