When I have examined my code in the past I find that my average function is about 10 lines. At a guess about 1/3 of those functions are public for whatever package they are in. Public functions get a comment. Function names are descriptive. Most variables are private to a function.

If I cannot find a descriptive name for a 10 line function that gives you some idea why that function exists, that indicates a problem in how I am breaking the problem up.

As with any personal style, it takes getting used to. And no, I don't always do a particulalry good job of it. But I don't think that modularizing less and commenting more would be an improvement.

Yes, you're a good coder and you write clean code. There's very little you'll release to production that I can't figure out mechanically, and vice versa.

There is, however, a great difference between understanding *what* you are doing and *why* you are doing it. This applies when working around bugs, when implementing business rules (which have, at best, a rather tenuous and dispassionate relationship with what we would call reality), and when doing things one way instead of another.

How else will other good coders distinguish between personal preference (using defined tests on variables instead of oring them in place with default values) and operations and assumptions necessary for your code to work.

I will only mention mere mortal programmers in passing.

Having recently come up to speed on a large and complex and evolving codebase with minimal documentation and no further hints as to its name and nature, I will repeat that understanding the mechanics of a program is rarely beyond the abilities of your average caffiene-stymied simian.

It is only discerning the will and the intent of the programmer that allows you to proceed without fear. That means coding by intent, expressing the design by way of metaphor (of which descriptive names play a part), and that means commenting your code with the assumptions you make and the reasons for any non-obvious decisions.

I find the most useful comments state what remains invariant, while the code states what gets transformed.

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.

I am not sure what your objection is. You are saying that most people don't do a good job? True but IMHO irrelevant. As the saying goes, there is no real difference between Perl scripting and Perl programming, but the ones who think of it as programming generally do a better job.

As you note, scripting the problem straight through makes it harder to understand later than programming it properly. As you mention, people often script and then try to solve their problems with volumes of documentation. At which point you have two problems instead of one.

Documentation is both good and necessary. It tells people what they can and cannot expect, it tells people what interfaces should be used and how to use them, it provides a spec by which the programmer figure out what the code should be doing, it provides something for testers to test and it helps users.

It does not replace the need to program well.