This topic has been the source of many spirited conversations where I work. What goes into a design doc? What goes into a user manual? What is the appropriate level of comments for code?

I personally find that a user manual should only tell the user what they need to know to use the tool (or library, or module, or class...), not anything about the internals (too much information, and the documentation won't be read). POD seems to be a useful way, and I would always recommend it.

When it comes to design documents, some people I work with state quite emphatically that their design document is the comments in the code. IMHO this is not sufficient. If I suddenly have to maintain someone else's code, a roadmap would be nice (i.e. these files contain the code that does x, so if x breaks, this is where to start). After that, the specifics of the design I do expect to find as comments within the code.

With regards to comments in the code, some of my co-workers write books at the header of each function/class. Others insist that there be a comment for practically every line of code. I, however, being rather old school, learned my habits before syntax highlighting full screen editors were available. The criteria for my commented code is: (1) use lines to outline main comments, and (2) the comments should read like a very general algorithm.

The reason I like my commented code to read like an algorithm is very simple. When I go back to it to add new stuff (there are always new requirements) or especially when looking for a bug, I can verify that the code does what it is supposed to do (as determined by the comments). If I don't know what it was meant to do, then it is much harder to know whether or not what it is doing is what it should be doing.

I have written parsers (in FORTRAN for FORTRAN) that would extract the comments, and then used the results for detailed design reviews. I found this to be very useful. To this day, before I consider a project finished, I will pass through one more time, ensuring the the comments reflect the intention of the code.

to include such documentation means to balloon the size of the source code
If I never had to maintain the code after the fact, I might not be so insistent about comments in the code. But I do, and I am.

Sandy

In reply to Re: The sourcecode *is* the documentation, isn't it? by Sandy
in thread The sourcecode *is* the documentation, isn't it? by dimar

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.