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.

In reply to Re: Too much documentation? by Sherlock
in thread Too much documentation? by melguin

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.