[figglesonrails]

Just no.

Well-written software (i.e. clean code, clear functions) is great and a joy to work with, but is absolutely not a substitute for documentation. Public APIs are double-triple-extra not exempt by merely being well-written, especially not C/C++ APIs, which have complex meta-details like "is this thread-safe?", "does this allocate memory?", "can I call this twice using the same object?", etc.

I get that if code is clear enough, it should be self-documenting. That alleviates the need to write as many comments. //Comments//. It's not a user manual. It's not an explanation of architecture. It's not a help guide. It's not an example of how to use it. It's not best practices. It's not how to write a plugin for your system. It's not an explanation of why the software is needed or where it fits into the business's plan. It's. Just. Code.

I've inherited enough undocumented code to take new stance: if I quit tomorrow and people are unable to train a new person to fully understand my code without me to train them, then I'm doing it wrong. "Wizards" are also liabilities.

[scrabble]

Ok, let's say that the code can double as documentation (which is what I stated), and not that the code doubles as all of the documentation.

The code should be able to provide you with the how and the why (supplied with proper testing that covers planned use cases, and comments when testing and code are insufficient.) When code is well written it will answer a lot of questions, I encounter this almost daily when reviewing code.

What code is not is a manual or instructions on plugin writing, etc. You are right on the money there. It's also not API documentation, again, right on the money.