Hacker News Reader

Comment by wry_discontent | Hacker News Reader

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.

View on HN

Have 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-a...

I 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.

IME 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.

They're really only for documentation and the simplest of single function unit tests.

The idea is to provide a DRY way to ensure that the examples are correct. Few things are worse than a wrong example.

That'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.

I can see that working for a functional language. But how do you specify the side effects?

You 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"

Python also has a similar concept: 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

I was surprised (and pleased) to find out that Rust has doctests as well.

On 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

esdoc also includes a linter which does the same

There'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.

Completely 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.

If 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.

That's the whole point of doctests: https://docs.python.org/3/library/doctest.html

Something 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.

Agree. This is why Typescript/Flow became so popular, because they break the build if the "doc" isn't right.

Reply on news.ycombinator.com