Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl Monk, Perl Meditation

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

Most of us hate to write specifications. They're seen as an onerous task and, for many small projects, an irrelevant one. Whether or not the task is onerous is purely a subjective opinion. Whether or not the specifications are irrelevant is not subjective.

Case in point: a simple form-to-email script.

My company is offering a product that has generated a huge amount of interest. In order to handle the unexpectedly large demand for information, we wanted to include an information request form on the Web site. I happened to hear my name mentioned by my boss and wandered over to catch the tag end of a conversation that was about what I needed to do. Coding a script that captures about 20 form fields is not particularly difficult. Untainting all of them can take a bit longer. My boss knows that I use a form-parser that I've written to automatically generate the form handling code. Thus, he assumed that it would take me about 15 minutes to write the script.


It actually took me about three hours, mostly because no specifications had been written. I was told to simply write a form-to-email script that would send us an email with a request for 8 by 10 color glossy photos (thanks, Arlo!) of our product. I was sent the link to the HTML form and that was my complete specification. Nothing, of course, was in writing.

Now many of you are probably thinking, what's Ovid blathering about? That's a piece of cake. In reality, it's a bit more work than it appears on the surface. Further, because no specifications were given and because the people who dreamed up this little assignment took off for a couple of hours afterwards, I was left to come up with the specification on my own.

I decided that the form had to be "sticky" (information filled in if the user is sent back to the form) because the user may not supply all of the necessary information. I went to the person who designed the form and requested a confirmation page (one would think they'd get the hint, since I request this for all pages where there's no way to verify that an action had really occured). Further, since I try to be sensitive to privacy information, I made all contact information, except for the contact name and address, optional. We needed to mail a brochure, but if someone doesn't want an email or follow-up phone call, then they can "opt out". I also realized that the server this was to be on didn't have Template Toolkit installed, but did have HTML::Template. However, no one here uses HTML::Template and I didn't have the authority to just go out and install the Toolkit. What do I do? Use "HERE" docs? Ugh!

On my first iteration of the script, I reluctantly used HERE docs because I had no idea what was intended. I got the confirmation page from the designer and had everthing running fine. Sticky fields, useful error messages about required fields, and a slick confirmation page were thrown together pretty quickly. Then my boss got back.

As it turns out, there were three completely different forms that I needed to capture information from. My required fields were wrong as we needed phone numbers and email to bug the heck out our potential customers with. And I could forget about the HERE documents as they want Template Toolkit on that server, anyway. I had a modest amount of my code that was now junk and had to be rewritten. A simple form-to-email script that should not have taken very long wound up taking several hours to write because I was forced to guess what was needed. Had specifications been written, I wouldn't have wasted my time and I could have gotten back to my regular work much sooner. The next time you're thinking about skipping clear specifications, think about this. If it's more complicated then the script that I described, how many hours are you going to waste?


Vote for paco!

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

In reply to Specify, Specify, Specify by Ovid

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, 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, 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.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others pondering the Monastery: (5)
    As of 2021-01-24 16:50 GMT
    Find Nodes?
      Voting Booth?