The ratio of a given amount of
source code that is dedicated to
comments.
The importance of comments cannot be overstressed, as understanding a piece of code is
always much, much more difficult for anyone who hasn't written it himself. And even the author often has problems understanding it when he looks at it years later.
Dismissing comments as unnecessary because Good code is self-commenting is downright wrong for most nontrivial tasks where the individual commands reveal little about what is actually being done on a higher level. Even if the code is self-commenting, natural language comments are usually easier and quicker to understand, especially in the case of high-level abstract descriptions of what a whole function, module or class does.
The Infospheres team of Caltech has this to say about the comment-to-code ratio in their coding standards:
- Horribly commented code averages 0-5% comment ratio.
- Poorly commented code has a 5-10% comment ratio.
- Average code has a 10-15% comment ratio.
- Good code has a 15-25% comment ratio.
- Excellent code has a > 25% comment ratio.
The code that we release averages approximately a 45% comment ratio.
Much of the
Linux kernel also serves as a good example, having a very high ratio of comments. So follow these exampes and don't be lazy.
Comment your code!