Normally working out how a complex piece of software works from only the source code is called reverse engineering. I've encountered this "readable code means

Normally working out how a complex piece of software works from only the source code is called reverse engineering. I've encountered this "readable code means I don't have to document" idea before. I have no time for it, it's just wrong: 1. Important things aren't easily visible in the code, most commonly why the code does a particular thing. "Readable" code, which is a very subjective standard, can only tell you what it does but not the underlying rationale. 2. Writing docs often exposes the fact that the way the code works, or is expected to be used, doesn't make sense or is sub-optimal. If your docs include lots of caveats or explanations of nonsensical behaviour then it's a good hint you should go back and think again. 3. Figuring out stuff by reading the code is often drastically slower than reading the docs. That's why all professional APIs have good docs and people grumble and moan when expected to use code that doesn't. 4. The sort of people who argue this, in my experience, often don't actually write readable code, they just tell themselves they do.