Always remember that the purpose of documentation is to make it clear to anyone (including youself, 2 months down the road) what the code is doing, or supposed to do, at least. Therefore, I think that the amount of commenting that you do will be dynamic. If you're doing some rather complex things, perhaps dealing with nested data structues, etc., you might need more comments (your 2:1 ratio). However, if you're doing something fairly simple and straight-forward, you'll obviously need less comments (your 5:1 ratio). How many comments you put in is really your judgement.

I feel that how complex something is not only relates to how complex the operations or data structures are, but also how complex the syntax is. IMO, I think one thing that endears Perl to so many here is that it is a very expressive language. That's great for the developer (less typing) but it's much harder to read. Therefore, I'd hope to find (in general) more comments in a Perl program than in a Java program. (Please note that I said "in general," so take that with a grain of salt.)

I've seen this go both ways. In one extreme case, I saw documentation plans that were so thorough that the developers wrote about 30 lines of documentation to 5 lines of code...for those scoring at home, that's a 1:6 ratio. Obviously, that's not good, as the documentation becomes more of a burden than a benefit. I've also seen code that has no comments in it. You already know that having no comments isn't good, or you wouldn't be posting, so I say no more.

To put it bluntly, I don't think anyone can tell you how much documentation is the right amount. That's really up to you. I like hearing someone say, "You should have 20% documentation blah blah blah" because it gives me something to shoot for, but that should only be a guideline. The real decision of how much documentation to have is up to you. Determine what you need to say to make the code make sense and say it, and no more.

I wish I could be of more help. Good luck.

- Sherlock

Skepticism is the source of knowledge as much as knowledge is the source of skepticism.