Much as I like Mythical Man Month, I think Brook's admonition on the necessity of code documentation is dated, and should be read as a statement about coding practices of that bygone era, when it was much more difficult to write code that could stand on its own without additional documentation than it is today.

At the time the book was written, most compilers (with the exception of COBOL) limited variable names to six or eight characters. It was hard to write code that clearly expresses its intent given that constraint. A reader needed additional commentary and documentation to help untangle cryptic fragments.

Contemporary methodologies (the Extreme Programming folks in particular) eschew commentary, and use the need for commentary as a hint that a piece of code needs to be refactored or rewritten. I don't agree with them entirely on this, but they do have a good point.

I'm not arguing that code needs no documentation. High-level overviews are always welcome. But we now have better tools than Brooks did when he was working on OS/360, and can use those tools to write more descriptive code than those in Brooks's era could. The trick, of course, is to do so.

In reply to (dws)Re: Re: Rules of Proper Perl Style by dws
in thread Rules of Proper Perl Style by sierrathedog04

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.