>Having said that, I find it helpful to write documentation before writing the actual code.
Do you write/have a technical spec? I think that's what you are describing. If I first and only write the comment, there can often be a disconnect between what the code does right now and what it would ideally do once I'm finished. On the other hand, a spec plus an accurate comment keeps everything in order.
The README is mentioned is more or less a lightweight specification of the public parts. Sometimes it warrants more detail and I add an actual SPEC document which goes into great detail.
I have not had much trouble with the comments diverging from the final implementation of a piece of code. But I have forced myself into a habit of re-reading through the documentation regularly once I've committed a chunk of new code. Just to ensure it all still does what it says on the tin. This takes extra time, but together with learning how to write decent commit messages, this has helped me keep things sane and organized.
Do you write/have a technical spec? I think that's what you are describing. If I first and only write the comment, there can often be a disconnect between what the code does right now and what it would ideally do once I'm finished. On the other hand, a spec plus an accurate comment keeps everything in order.