Comments are a hack. There should be a way to include structured documentation with code that lies somewhere between free-form text (comments) and actual code. This documentation should sit at the abstraction level high enough to provide insight not captured in the code directly, but low enough that it actually has some coupling with the implementation so that if the implementation changes the documentation will be broken.

Of course, as long as we are using ASCII text for editing code, this is impossible. A few people are working on fixing this flaw (Intentional Software, Jetbrains MPS) but don't hold your breath!