Conventional wisdom holds that the solution to the problem is documenting the code appropriately. Conventional wisdom is wrong. Reasons are manifold, and quite obvious once you start to think about it.

Documentation is always out-of-date. It’s impossible to have anyone and everyone who updates code to update the comments and documentation accurately. Sure, you could try, but to a large extent, this is simply beyond your control. Typically, this means you need to assume the documentation is wrong and read the code in detail anyway, so you might as well simply start by reading the code.

Reading the code is the only way to figure out what it is doing. Documentation only tells you what somebody thinks the code is doing. It is quite possible that they’re wrong, or only partially correct. Besides, it’s better to build up a model of what you think the code is supposed to do, than to be told what to expect.

Code is more concise. If the code is well-written and self-documented, it is generally faster to read the code and understand what’s going on than to read the comments (which are, by definition, more verbose than the code they attempt to explain). And if you can’t trust the programmer to write good code, you can’t trust the guy to write good documentation either.

There are some situations where documentation is necessary, of course. Examples would be when you are attempting to explain the motivations or structure of your design at a larger scale, or if you want to explain what the code is not — why you decided to something one way and not the other.