Whoever has to fix code from another programmer will say as many comments as possible. The big problem with old code is: "You see what the code does. You see that this is the problem. But you does not know why the programmer wrote it like this."
To understand a bug you need to know:
- what should the code do (not what the code does) and why.
- The contract of every function. For example if there is a NullPointerException then where is the bug? In the function or in the calling function?
- On every Hack is to described how the problem can be reproduced (Language version, OS, OS version). For example we have many hacks for an old Java VM that isn't supported anymore. But we are not sure if we can remove it because we don't know how to reproduce them.
We have a ratio of 2-3%, which is too few. I think that 10% is good for large or long lived projects.
