5 ms·
As the dictator author/maintainer of a tiny library¹ (45 functions total), I can confirm the manual wouldn't be half as good without external contributions. And
by loup-vaillant 3y ago
As the dictator author/maintainer of a tiny library¹ (45 functions total), I can confirm the manual wouldn't be half as good without external contributions. And I daresay this manual is a major contributor to the usability of the whole project.
As a new user of libcurl, I was recently able to quickly implement FTP upload and adapt it to our specific use case thanks to their tutorials and API documentation. I was even made aware of the lack of thread safety in old versions thanks to that same documentation, so I could warn my team that we should update.
Documentation is bloody important. Almost as important as the code and the test suite themselves.
[1]: https://monocypher.org https://monocypher.org
- SAI_Peregrinus 3y agoIMO a big portion of what a good test suite should be is documentation. Tests are examples of things that do and don't work, with some explanation of why. Examples in documentation can (for some doc frameworks & languages) be set up to run as tests, ensuring they stay current and actually work. Tests are machine-readable documentation.
- deleted 3y ago[deleted]
- zilti 3y agoOh yes, and for languages where that is not directly possible, there are still ways - I implemented libraries for Chicken Scheme in org-mode with org-babel; the examples are simultaneously tests, runnable directly from within the org file, and live next to the code together with the docs. org-babel's tangle and org's export take care of the rest.
- rqtwteye 3y agoI subscribe this to a certain degree but there are limits. Some tests are just too complex to be used as documentation. Sample code is better in such cases.
- ramijames 3y agoThis is ALWAYS TRUE. Software without good documentation pales in comparison to software with good documentation. https://www.ramijames.com/thoughts/docs-deserve-more-respect https://www.ramijames.com/thoughts/docs-deserve-more-respect
- Just_Harry 3y agoThis is something I _really_ like about D. Unit-tests are built into the language, as is comment-based documentation—put those two together and you get unit-tests as documentation examples built into the language; all it takes is to put a documentation comment (which can be blank) right before a `unittest` block after a declaration. E.g. the examples for the D standard-library's `curry` function are just unit-tests: the docs: <https://dlang.org/phobos/std_functional.html#quickindex.curry https://dlang.org/phobos/std_functional.html#quickindex.curr...>; the code: <https://github.com/dlang/phobos/blob/42b8c65ccfd35c863f7cedfd20794a125615c49b/std/functional.d#L909-L1010 https://github.com/dlang/phobos/blob/42b8c65ccfd35c863f7cedf...>
- deleted 3y ago[deleted]
- hitchstory 3y agoI took the same "docs are tests and tests are docs" approach with integration testing when I created this library: https://github.com/hitchdev/hitchstory https://github.com/hitchdev/hitchstory I realized at some point that a test and a how-to guide can and probably should actually be the same thing - not just for doctests (https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html), but for every kind of test. It's not only 2x quicker to combine writing a test with writing docs, the test part and the docs part reinforce the quality of each other: * Tests are more easily understandable when you attach written context - the kind that is used when generating a readable how-to guide. * How to docs are better if they come attached to a guarantee that they're tested, not out of date and not missing crucial details. * Integration test driven development where how-to docs are created as a side effect is really nice.
- abdullahkhalids 3y agoYou can put tests in python's class/method docs. They work wonderfully if you put enough examples to cover most inputs/outputs of the function.
- SAI_Peregrinus 3y agoYep, also D and Rust have similar things, and likely other languages. I didn't feel it particularly useful to try to list them all, just to point out that tests & docs are two aspects of the same thing.
- loup-vaillant 3y agoThat depends on what we're testing, and how thoroughly. Tests as documentation are amazing when the specs are in flux and we'd rather document stuff in one place instead of duplicating it between tests and user manual. But when the specs are fixed this is much less of a problem. Then there's how much you need to test. Good tests go way beyond readable examples, they usually involve generating tons of tests with more or less random data and running them in a loop (property based tests). I do this, and to be honest I wouldn't recommend end users read them.
- SAI_Peregrinus 3y agoAgreed, that's why I said it's a "big portion" and not "all" of what a test suite should be. Many tests are "how-to guides" in the Diátaxis documentation approach[1]. They're also useful as a part of tutorials. Anything over 25% is a pretty big portion of the total documentation. Automated property-based tests, fuzz tester cases, and similar things aren't documentation at all.
- 1-more 3y ago> Examples in documentation can (for some doc frameworks & languages) be set up to run as tests, ensuring they stay current and actually work. As an example, in Elm (as in many languages) your publicly exposed functions in a package (a.k.a. library) are required to have documentation comments. This often includes a simple example because, well, it's easy to grasp. The build tool elm-verify-examples runs all of these examples and verifies that the output is what you say it is. It pretty cleverly uses the inline comment delimiter as the start of an arrow so that the rendered code listing in the example is still syntactically correct. https://github.com/stoeffel/elm-verify-examples https://github.com/stoeffel/elm-verify-examples
- actionfromafar 3y agoMy heart skipped a beat when I saw there are PicoLisp bindings!
- LtWorf 3y agoI opened your link and don't know what it does.
- bo0tzz 3y agoIt says what it does in the first sentence on the page. > Monocypher is an easy-to-use crypto library.
- marcellus23 3y agoYep, and if you don't know what a crypto library is, the Features list does a very good job enumerating all the things the library lets you do. I have no idea what the GP is talking about.
- jholman 3y agoA warrior does not trifle with secret messages! Have you no honour?
- loup-vaillant 3y agoEdit: Oops, replied to the wrong user. Diplacing it here: https://news.ycombinator.com/item?id=39375470 https://news.ycombinator.com/item?id=39375470
- marcellus23 3y agoI think you misunderstood my comment. I'm not saying that I don't understand what your library does.
- loup-vaillant 3y agoOh crap, I meant to reply to @LtWorf, and somehow botched it. I’m moving my comment, let’s say no one will ever know.
- 3y ago