3 ms·
Indeed! There's no better documentation than the code itself. Except for all the things you need to know in order to use the code. Which are why you still writ
by ubernostrum 8y ago
Indeed! There's no better documentation than the code itself.
Except for all the things you need to know in order to use the code. Which are why you still write actual real honest-to-God prose documentation. Or, if you don't, is why I don't bother trying to use your code.
- jerf 8y agoIf you read the links given, you'll see that is in the godoc. Godoc has a place to put prose documentation. The formatting is quite weak (you get headers of more than one word, paragraphs of text without italic or bold but with URLs turned into active links, etc, and preformatted-code), but it's often enough. (If it really isn't enough, link somewhere.) Godoc also has official support for examples, which are included in the documentation and tested as part of the automated test suite, ensuring they stay up to date if written even halfway reasonably. This is not specific to godoc. Most, perhaps effectively all (certainly all the ones I've seen and used), automated code generation tools have a place to put arbitrary prose at the top. The fact that it is so often unused is a developer problem, not a tool problem.