Any assumptions should really be coded as assertions and the comments should explain why the check is there. Really? What should the code do if, once promoted to production and deployed, the underlying assumptions are found to be wrong? What should those assertions *do* if they fail?

It depends a lot upon the implications of the assertion failure, and it's often not an easy problem.

What should I do if I catch a "POWER OUTAGE" signal on a machine with no UPS? It can't logically happen; so how should I code to handle it? Anything follows logically from a contradiction, so logically, any response I choose is wrong.

What about just an I/O error from the disk? Should I write a message to the logfile (on disk) complaining that the disk is broken? Should I spam the user with repeated console messages? How do I continue after such a failure?

It's bad if a program aborts when it doesn't need to. It's also bad if a program continues when it shouldn't. If you've got an situation that you didn't code for (can't legally happen), you don't know what to do.

For example, why did you choose to die() in one case, and warn() in another? Why not carp() or croack() instead?

The documentation for the *function* should tell the caller what the correct inputs and outputs are, and what error handling, if any, there is.

That way, if I call your spiffy new function with data that I haven't vetted, I'll *know* what the error handling for the routine is, and whether or not it is suitable, without having to wade through the ugly implementation details of your code. Reading code should be a thing of last resort; documentation designed for humans should be the first avenue of attack, and only when code is broken should it have to be investigated manually.

If you can't explain what your function does in plain English, then you need a simpler function (or English language lessons). Or both.

-- AC