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

In reply to Re^3: Meaning of Maintanability and Functionality in Coding Perl by Anonymous Monk
in thread Meaning of Maintanability and Functionality in Coding Perl by neversaint

Title:
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, details, 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, summary, 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.