3 ms·
Code as documentation feels like a good idea because code is the only reliable source of truth. But it also assumes that code can comprehensively express all as
by alpaca128 4y ago
Code as documentation feels like a good idea because code is the only reliable source of truth. But it also assumes that code can comprehensively express all assumptions and other info, which sounds more like wishful thinking.
Auto-generated API docs combined with handwritten documentation that covers what can't be expressed in code and includes some useful examples seems like the right approach to me. In practice that's the kind of doc I tend to have the best experience with. For example the Rust stdlib docs are auto-generated but the language also supports notes and (automatically unit-tested) examples in docstrings which means the API docs are filled with explanations & examples and mentions what assumptions are made about inputs.
- hitchstory 4y agoI built this framework coz while I didn't believe in "code as documentation" I did believe that example based specifications, tests and documentation were all sort of the same thing (triality): https://hitchdev.com/hitchstory/ https://hitchdev.com/hitchstory/ The difference between this and behave/cucumber is that the A) specification language allows for more complex representations and B) there's a templating step to generate readable documentation.
- eevilspock 4y agoI'm not sure if you're saying that rust stdlib docs do this but documentation where all the examples are themselves runnable as tests and included in the CI test suite solves so many problems.
- steveklabnik 4y agoNot just the stdlib, the documentation tool itself supports this, so it's the case for any Rust package that writes documentation.