Hacker News Reader

Comment by toxik | Hacker News Reader

Honestly, reading the headers is the only way to understand iOS, macOS, and iPadOS properly.

I find that the older I get, the more _code is my documentation._ Particularly for things like Python's matplotlib, once you do more than put lines or scatter plots together, you _have_ to understand how the code actually works.

Of course, that's difficult when all you get is header files, but still...

View on HN

"Code is the documentation" has to have boundaries though, or else you'd have to understand the entire system down to the instruction set in order to print hello world.

Within a small/medium codebase, code is documentation is mostly okay, but for libraries and abstractions you really ought to have solid API docs.

I get the mindset and am very much a read-the-code person as well but my go-to example for this kind of thinking is that reading the code in lieu of a written summary/guide, etc is like trying to understand a book where the chapters and paragraphs are mixed around. It's possible and the ability to do so worthy of pride but it's clear that a succinct summary in one place would be far easier and time-efficient.

Not to say that heavy documentation like this is perfect of course. It just seems like the complexity of the read-the-code solution is sometimes glossed over.

Right, that’s the thing isn’t it—sometimes an abundance of documentation is actually not a good thing. matplotlib is a good example, its documentation fails to convey the common arguments and to what degree they are universal or not; reading the code is really the easier way in the end.

Reply on news.ycombinator.com