9 ms·
I have yet to see anything that actually documents well other than code itself. Comments are _always_ subject to the problem of going stale or being poorly wor
by wry_discontent 9y ago
I have yet to see anything that actually documents well other than code itself. Comments are _always_ subject to the problem of going stale or being poorly worded. I haven't played with it much, but Clojure's spec looks like a good tool for documenting how functions should behave. That plus a description in the docstring might be the best thing out there right now.
- ch4s3 9y agoHave you seen Elixir's doctests[1]? They're docs with a code example that gets run by your tests, and if the example doesn't work, your tests fail. [1]https://elixir-lang.org/getting-started/mix-otp/docs-tests-and-with.html#doctests https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...
- wry_discontent 9y agoI haven't seen that before, but I really like it. I've thought before that it'd be a good idea to include tests adjacent to the code they're testing before, but I'm not sure of a good way to do that, particularly in Javascript.
- masklinn 9y agoIME it's an OK way to show examples which are validated (and thus don't get broken as the API changes), but it's really not a good way to have actual tests. Terrible debugging experience aside, actual unit tests just make very little sense as part of a documentation.
- ch4s3 9y agoThey're really only for documentation and the simplest of single function unit tests.
- pmontra 9y agoThe idea is to provide a DRY way to ensure that the examples are correct. Few things are worse than a wrong example.
- masklinn 9y agoThat's a fine idea and exactly why doctests exist but I am specifically replying to a comment talking about tests. Not testing examples, having actual tests included in the documentation. Which, again, experience taught me is a terrible idea.
- amelius 9y agoI can see that working for a functional language. But how do you specify the side effects?
- ch4s3 9y agoYou would have to assert equality on the value of the data/file/whatever being mutated. Here's an example: ##Examples iex> user = Repo.insert!(%MyApp.User{id: 1, some_state: "whatever"}) ...> {:ok, user} = MyApp.Users.DataTransformer.transform_with_effects(user) ...> Repo.one(where: MyApp.User.id == 1).some_state "new state"
- forsaken 9y agoPython also has a similar concept: https://docs.python.org/2/library/doctest.html https://docs.python.org/2/library/doctest.html Sphinx also has additional doc testing methods that let you test the code examples in your actual docs: http://www.sphinx-doc.org/en/stable/ext/doctest.html http://www.sphinx-doc.org/en/stable/ext/doctest.html
- sjellis 9y agoI was surprised (and pleased) to find out that Rust has doctests as well.
- kozhevnikov 9y agoOn subject of going stale, there is valid-jsdoc ESLint rule that will ensure doclet comments are kept in sync with ever-changing signatures. http://eslint.org/docs/rules/valid-jsdoc http://eslint.org/docs/rules/valid-jsdoc
- wdfx 9y agoesdoc also includes a linter which does the same
- softawre 9y agoAgree. This is why Typescript/Flow became so popular, because they break the build if the "doc" isn't right.
- weego 9y agoCompletely agree. There is no reason (outside of some kind of coding challenge) for code bases in the web domain to contain logic that is so obtuse due to hacks or unavoidable complexity that spending more time to document functions than it took to write them is the correct use of business resource.
- talideon 9y agoThat's the whole point of doctests: https://docs.python.org/3/library/doctest.html https://docs.python.org/3/library/doctest.html
- brudgers 9y agoThere's a reason The C Programming Language is one of the most influential books in the history of computer programming...and probably still worth reading today even if a person is not likely to become a C programmer. Its prose describes and explains the code and helps a person understand it. On the other hand, the prose is not comments. The prose is literature. Or to put it another way, the way to learn how to use Clojure's Spec is not from the names of functions in the Clojure Spec source code. It's from reading blogs and watching videos and listening to podcasts and reading the documentation. And the bar for Clojure Spec is pretty low. It just has to be better than JavaDoc.
- deleted 9y ago[deleted]
- deleted 9y ago[deleted]
- slackingoff2017 9y agoSomething like this has been around a while in the enterprise world. Take a look at Cucumber for Java or the C# port SpecFlow. The test cases are the documentation.
- moomin 9y agoIf you like Clojure.spec, you'll love a proper type system. ;) More seriously, keeping comments up to date is hard, but there's no alternative if you want to maintain a public API.