[chii]

> When everything is "just data", you spend a lot of time digging deep in libraries trying to figure out exactly what shape the data should take

or that is a good spend of time where you familiarize yourself with said library (as they say, the documentation is the code!).

Usually the library is well written enough that you can browse through the source code and immediately see the pattern(s) or keys. The additional experimentation with the REPL means you can just play around and visually see the data in the repl.

A spec does similar (and it does make it easier to seek through the source to find it).

[psd1]

I've often got value from digging through libraries (in other languages), but I've almost always had the feeling that I'm not "doing it right", or that someone somewhere isn't "doing it right". Logically, the concept of encapsulation doesn't extend to meta-coding, but it feels like it should, by symmetry. It feels like I'm breaking encapsulation if I use the knowledge I gain from poking around when I code to the library.

I'm fumbling at the concept of a library surface not being self-describing but I suspect I lack some concepts; does this thought lead anywhere? Can anyone give me a clue?

[chii]

I suppose if you examine the behaviour of a library, and code against that, then it is possible that the behaviour is unintentional and thus you end up being locked into a bug. This is most clear when the library is supposed to follow a standard (e.g., parsing some format), but is bugged and didn't do it right - and you code against that buggy behaviour.

However, that's an extreme case imho - you do that when you can't fix that library's bug or wrong behaviour.

But for things like key names and such, i dont think this applies - those key names are part of the library's api - and i often find that clojure libraries don't document them (or do but it's one of those auto-generated docs that dont mean anything).