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
[download]

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
[download]

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 :-)

Cheers,
Ovid

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

---

---

• Are you posting in the right place? Check out Where do I post X? to know for sure.
• Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:

  <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>

• Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
• Want more info? How to link or How to display code and escape characters are good places to start.