Documenting code is, for the most part, useless. It takes way too much time to keep it up to date. it's easier to just get in there and READ the code. Sure, document the larger, overall, architecture and how all the pieces fit together, but don't try and document all the details. It really isn't worth it.
While understandable for code bases where you have access to the underlying code, with iOS and macOS development, you have no such luxury. Good documentation is a must. I’d argue it’s a huge time saver even for open source libraries.
In the case of understanding a system you’re contributing to, you’re only half-right. Often code includes decisions, assumptions and designs which aren’t onvious from the code itself. It’s pretty common to understand how it works by reading it, but not to know why it was made to work THAT way; not to learn about the problem the code attempted to solve. It’s very hard to capture even when you’re rigorous with naming conventions and don’t abuse patterns and idiom.
So relying on reading code also relies on having the people who wrote the code available to explain the “why”. Or documentation.
Comments are for telling the reader why something is the way it is. The code doesn't do that.
It's also a lot more effort to dive into the code to understand what a method does (again, this typically includes background information related to things outside of the method itself) than to read an ideally well-formed sentence that precisely answers the main questions about the method's usage.
Unfortunately, reading the code would be a felony for me. I sort of feel that if Apple makes it a felony for me to do the obvious and fully sufficient thing, then maybe they need to pick up the slack they created.
