importance of documetation

I used to hear from some people that code documentation is very important. Of course I agree with those people but I have some suggestions that might make clear this point of view. Don't document the code. Write good/readable code instead. If you can't read the code w/o documentation that means that the code is bad. And this code should be rewritten. Self-documented code will avoid out-dated documentation. I have some experience with the code that had been changed but documentation hadn't been. I've spent tons of time to find out the bug. You might want to say me that you always update your code comments. But I want you to think about bugfixes, especially about HOT bugfixes. You don't have time to update the documentation - your first priority is to fix the code and to test the changes. You don't think about the documentation. You think about the code. Use clear names for variables/routines. That will help you to understand what some block of code does. Write in English/Russian/Portuguese/etc. instead of c/c++/python/etc. Don't be afraid of long names. Be afraid of names that don't mean anything at all. Document headers/declaration. That's not that bad if declaration of function/class/etc. is outdated. If routine doesn't do what documentation says you might want to see the code and to fix the code or to fix the documentation. Your friend probably won't use it what's not that bad. It avoid possible problems. =) Find some time to update documentation. It's much easier to update the declaration documentation because you usually know what routine does or what it should do. By the way it's much easier to navigate through the declaration documentation than through the code documentation. Usually code documentation is spread in the code and you have to spend some more time to find it out. During documentation update you might eventually discover that you can improve the model of your application/module/class/process/etc. If you maintain any code you should make a habit to write good code and don't document it; to document the declaration; to make some time to update the documentation. I suppose that these three simple habits will make you life easier ;). Be simple. Don't think that documentation can only help and your treatise of the process is correct.