Comment Re:Measuring readability (Score 1) 545
The developer can add comments, or rename variables, or restructure the code to make it clearer, but the end result should be readable code with fewer bugs (bugs live in hard-to-understand code, simply adding some intermediate variables to a complex formula can make them go away)
"Don't get suckered by the comments -- they can be terribly misleading. Debug only code." -- Dave Storer
This is why I always add my documentation at the end. A good programmer knows how to use his debugger. Properly named variables and methods will allow you to step through a program until you understand how it works. Once your understanding is clear, and you are quite certain that the code is good enough for somebody else, add enough documentation to aid other programmers in using or maintaining your code. The only way to know how much is needed is through the code review. The only exception I can think of to this process is when releasing the source code to the general public or to a client for their own maintenance. Since you don't usually have a code review with them, it's best to go for overkill. A pain sometimes, but a necessary part of a complete product.