If you're in a programming shop then maybe that's a reasonable assumption. However, I work with a bunch of Telecommuncations engineers. One of the guys is pretty good with MS-Access and VB Script but I'm the only person in the group that knows anything about Perl. And I am not a programmer. The last time I did any serious programming it was on an IBM 360 in PL/1 with punch cards. I'm a general computer/network geek that got saddled with the programming tasks because I'm the resident "Data Guy". In a situation like mine, it's NOT reasonable to assume that the person who comes in behind me one day will know any more Perl that I did when I bought the Perl Bookshelf CD lo these many months ago.

When my boss asked me to take this on, the primary focus was to update some scripts that had been written by one of the IT guys who had since left the company. Trying to figure out what he was doing was next to impossible since he had written the code assuming that he would be the only person to ever maintain it - or so I assume since he didn't indent, didn't use whitespace and didn't comment anything...ever. I had to figure out what groups of programs to look at based on their file names and when they ran - "This output file has a creation time of 20:38 so I'm looking for a program that runs sometime before that."

I have to agree that comments and documentation aren't supposed to be a tutorial but it's nice when a) they exist at all and b) they are comprehensive enough that you can follow the general flow of the program without having to read the code.

Just my opinion...

Jack

In reply to Re^3: top ten things every Perl hacker should know by jcoxen
in thread top ten things every Perl hacker should know by apotheon

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.