[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).