Hacker News Reader

Comment by danneu | Hacker News Reader

The opening paragraphs really resonated with me including that code example that can be replaced with any function I wrote yesterday.

A lot of my time in Clojure is spent re-reading and repl-evaluating my function implementations just to remind myself what its symbols look like. Even code I wrote an hour ago. Often I stoop to the level of caching my findings in a docstring/comment.

    (defn alpha-map-sum-combining-thing
      "TODO: Think of better name.
       Example input: {:a 1 :b 2}
       Example output: {[:a :b] 3}"
      [alpha-map]
      ...)

Sometimes I can spot abstractions and patterns and protocols that unify a namespace of functions so that their inputs/outputs are obvious, but often I can't.

This kind of tool is essential for me.

View on HN

I do this a lot:

"Often I stoop to the level of caching my findings in a docstring/comment."

I am not ashamed of this. When my co-workers have to read what I wrote, this kind of information makes clear what the function does. If I don't do this, then they will eventually figure it out by running it at the REPL and examining the input and the output, but if I document that in the docstring, I have saved them a lot of time. I also make it possible for them to actually read the code -- otherwise they can't really read it, expect by repeating it at the REPL.

Yeah, you're right. I would love if every Clojure function came with an example input and output.

What I meant to suggest is that my docstring example is something that could be expressed in code.

This would let you run tests, too: https://en.wikipedia.org/wiki/Doctest

On the other hand, why not just make it statically typed and list the types for each function?

A friend of mine has been doing similar things with the Swagger documentation spec (https://developers.helloreverb.com/swagger/)

While browsing the docs in a web browser you can fill out some fields for input and see what the output for that input is.

My friend forked it and extracts and lists any example data so you can click to load that example into those fields (my idea!). I tried it out and it's a very nice way to learn/explore a new API, especially testing edge cases where the docs are ambiguous.

It really hits a sweet spot when you have documentation browsing, live execution and example data. I think creating a similar interface combining docstrings, the repl and example data from test fixtures would be a nice tool to have (I find doctests to be one of those things that are better in theory than in practice as they get too long and maintenance is annoying, although perhaps a more literate style in your source code would change that).

You would think that being most functions being pure, that these types of docsctrings would be more common (or standard, even).

This is exactly what R does. It's a huge timesaver. Best. docs. ever.

May I suggest stealing some of core.typed's syntax for your docstrings, especially for polymorphic functions?

It scales very well, from simple types like clojure.core/symbol:

https://github.com/clojure/core.typed/blob/57da1175037dfd61c...

to polymorphic types like clojure.core/repeat:

https://github.com/clojure/core.typed/blob/57da1175037dfd61c...

to succinct representations of complicated polymorphic types like clojure.core/fnil

https://github.com/clojure/core.typed/blob/57da1175037dfd61c...

and I'll spare you the really insane annotations.

Of course you can pick and choose what's to your liking.

Here's a brief tutorial on type syntax: https://github.com/clojure/core.typed/wiki/Types

Thanks! I definitely have personally run into the issue a lot and our Clojure teams at Prismatic struggled with commenting discipline. We find schemas are easier to maintain and apply, plus they save a lot of time during dev and testing.

This has been my experience also, even as I'm simultaneously learning clojure and building my own webapp.

Reply on news.ycombinator.com