Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
tilly, while I agree in theory with what you are saying, I have a problem with this.

Let's say I have a program that reads an initialization file, opens a data file, does some processing, summarizing, error reporting, etc. A simple outline of the program might run like this (sorry for the formatting):

|--initialization--|--read .ini file | |--set globals | |--open files | main-|--process ledger--|--while not eof | | | | read next line |--addToProcessA | | | | | determine type--|--discard | | | | | write to file |--error reporting | |--termination-----|-- summarize results | write summary to file | close file
If that's the case, it's relatively simple to document and follow the process flow. But, even for a simple process like this, here's what I usually find in production programs:
read .ini file set globals open files while not eof read next line determine type addToProcessA -or- discard -or- error reporting end while write results summarize write summary to file close file
It's a fairly linear run-through from top to bottom. There is little if any attempt to modularize the code. When that gets significantly larger, documentation becomes critical. I'm not disagreeing with how one should write the programs (small functions are the way to go), but many, if not most of the programmers that I have met simply don't appreciate this.

As a side note, I find that even those who do appreciate this will often do the straight run-through rather than the modularization. I sometimes have that in my code (usually a sign that I've been given rotten specs).

As a second side note, I just hacked together the example. There's no serious attempt to make the names more sensible or to really break it down properly. I'll call it pseudo-Warnier-Orr :-)


Join the Perlmonks Setiathome Group or just click on the the link and check out our stats.

In reply to (Ovid - Yes, but) Re(?): What you want and perl advocacy gone way wrong by Ovid
in thread module info by ivory

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, 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, 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.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others perusing the Monastery: (3)
    As of 2019-07-20 09:52 GMT
    Find Nodes?
      Voting Booth?

      No recent polls found