Is this a documentation problem? I often do this when documentation doesn't entail how things work under the hood. E.g. document doesn't unwrap all the magic logic.

One of the biggest downsides of using python -- not that you can't look under the hood -- but often it's a bit scarier

what a coincidence. recently had huge discussion at workplace regarding writing documenting APIs vs writing Really Obvious Code in monorepo. it is nice to dive into source if it's well written with good naming and SRP, but it's not always the case

It's always amusing to me when I can identify from the docs that the lib is like 100 lines long. I'll usually just use those small ones as inspiration.

I take it you've never worked with JAXB

"Good design" partially means reading the docs is sufficient and you wouldn't need to look under the hood. Sometimes good docs can cover for bad design but usually not.

Edited my first library this week and felt like a magician.

it's really powerful if the compiler/interpreter of the language you are working with is itself written in that language. To really understand Ruby/PHP/Python, you have to study lots of C, with Go you don't have that problem.

+1. Prob the most useful thing I learned at Google was how to read lots of code very quickly. It is a force multiplier to know exactly how your dependencies really work. It’s surprising to me how rare this trait is. I don’t think most eng proactively read code they didn’t write

This isn't surprising given that documentation is either auto-generated and thus limited, done at the end to satisfy a to-do item and thus also limited, or passed off to an intern or third party and hence limited. Techies don't like documentation, so they de-prioritise it.