If you can't understand a statement without pausing to think, re-write it. If it isn't obvious why the statement is in the current function, document the function better. Explain how the statement fulfils the purpose of the function. If the statement doesn't have anything to do with the function's purpose, move it elsewhere or delete it.

Not every line of code belongs in a function, of course. Optimize to minimize confusion: if a descriptive name is more clear than reading the corresponding code, the code belongs in a function of it's own.

Document your functions. Explain their purpose, their limitations, and any assumptions about how they will be used or called. Explain any side effects. Document the error handling (and think about error handling).

Even if you're throwing away a big section of "junk data", make what you're doing and why as clear as possible. The variable names should explain what the source of the data was. The search or filter function call should explain what data you want to keep. The pod documentation for the calling function should explain the requirements for the function. Based upon those requirements, it should be clear why you need to keep the data : if it isn't, document it.

I use normal pod for the user documentation. That way, "perldoc <programname>" always explains how to run the program.

For the code documentation, I use a special feature of pod. I mark my code documentation with the '=begin <translator>' and '=end <translator>' pod directives. (I call my translator program "programerdocs".) My programmerdocs pod translator program just translates 'programmerdocs' lines into normal pod, by adding an '=pod', then filters them through the normal pod translator. This way, I can maintain two independent sets of pod documentation: one for end users, and one for coders and testers.

My goal is that a skilled tester could take the internals documentation, and write unit/integration tests for all the functions, without ever reading a line of code. If they can do that, I know it's properly documented.

If you need to add a statment before the end of a loop, would you rather see:

     }
    }
}
}
[download]

        } # end loop over records from input file
   } # end loop over files
} # end read_records()
} # end block of variables private to read_records()
[download]

It also helps me out when I have a program with one too many or too few braces: I can quickly match what a brace actually does match with (using % in vi), and compare against what it should match.

Never assume your audience knows your project's business rules, implicit assumptions, or so forth unless there is an excellent reason to assume this will be true. Remember that programming staff come and go, so try to ensure that the costs of excessive documentation are balanced against the risks of information loss.