[throwawaylinux]

> The fix is to properly document your code.

I disagree that is the fix. I've seen horrible code that has extremely extensive documentation, and nice code with minimal documentation. I know which I would rather work with.

Documentation has its place, particularly for high level concepts and shared data and interfaces, and tricky, exceptional, or surprising things in the code itself. But it's a poor crutch for bad design or code.

[cratermoon]

This is 100% correct. There's no amount of writing about code that can make it better. In fact, if you can write well about what the code is doing, you can write the code well. It's a mystery to me that anyone expects people who can't write code that's clear and simple to then be able to write clear and simple prose explaining it. It's actually much easier to write code that only the computer (compiler or runtime) can understand, but it doesn't care if you name things meaningfully or if the structure reflects the problem domain.