3 ms·
I tend to use in-code documentation[0]. Works pretty well. Could still [theoretically] go out of date, but that hasn't happened, so far. The one thing that do
by ChrisMarshallNY 2y ago
I tend to use in-code documentation[0].
Works pretty well. Could still [theoretically] go out of date, but that hasn't happened, so far.
The one thing that does happen, though, is copy/pasta errors. I'll copy a bunch of code, including the headerdocs, and paste, but forget to adjust the docs.
[0] https://littlegreenviper.com/leaving-a-legacy/ https://littlegreenviper.com/leaving-a-legacy/
- pasc1878 2y agoBut it covers only how to use a function if you know what the system is meant to do or know which function to call in the first place. You need some overalls documentation to explain the concepts and how to put things together. When the user understands that you can use in-code documentation but even then only if you need to use one function at a time - there needs an explanation of how to put things together.
- ChrisMarshallNY 2y agoThat's what I use the README for. With Apple's docc, you can drop READMEs throughout the system, and they show up in Xcode's doc browser (and can be referenced from the code).
- eddd-ddde 2y agoIntegration tests? They show how the system works as a whole, and they don't go out of date.
- ChrisMarshallNY 2y agoThey are, indeed, useful. I usually create full-fat test harnesses[0] for my stuff, as that gives a totally realistic implementation example. But I think having a well-written README is more likely to be useful. API/implementation documentation (whether docs or tests), are much more likely to be read, than end-user docs. [0] https://littlegreenviper.com/testing-harness-vs-unit/ https://littlegreenviper.com/testing-harness-vs-unit/