The majority of programmers would agree on that documentation is very important, but most of us find writing it quite boring. It is seldom creative and hardly what we would term "productive". It often feels redundant as the logic is implicit in the code anyway and are prone to change. We should seriously think about changing that perspective because when we enter another one's code we often wish there was an explanation to all the mess!
I believe we have to stop documenting the logic in the code, unless it is very complicated. Usually we can easily interpret the code by simply reading it. What we need to do instead is to explain WHY we have chosen the present logic. Most likely, there is a perfectly good reason for it and that will be important for future maintenance work and development to understand. Not only will it help us to quickly comprehend each other’s code, it can also help us distinguish business rules or technical logic that should be locked away into a subroutine.
The race of humans are known for its sense of stating the very obvious. A notion Ford Prefect in the Hitchhikers guide to the galaxy caught on early as in "It's a nice day", or "You're very tall", or "Oh dear you seem to have fallen down a thirty-foot well, are you alright?" Instead of sharing the obvious in the code, let us start explaining the choices we have made and in the process asking ourselves better quality questions: "Hm, WHY am I limiting the search to foreign keys 36, 38 and 74?" THAT certainly would have made my world a lot easier many times!