Indeed, as the maintainer of several modules, it is quite difficult to keep the documentation up to date, but that's just one more place for module adopters to help.
Comments are a different story. Many times I put the comments first - to remind me what I wanted to do. But I do try to use comments where things aren't very obvious. Again, you are welcome to install the Coder module and let us know when we missed something.
Nancy Injustice anywhere is a threat to justice everywhere. -- Dr. Martin L. King, Jr.
From: tony maciejowski
It's the old problem of why many programs are insufficiently commented. There is never time to take a deep breath and go back and write cogent comments.
It seems to be happening in Drupal too despite links like below (But thanks for the good intentions and motivational jibes). The good docs I find are most of the time outdated. Understandable given the pace of change here.