[thelist] CF: Error Trapping: Tip & RFC

[Frank]

So now I'm tightening up a lot of stuff in my apps. I'm into error 
trapping. Nothing freaks a client out more than the diagnostic page. 
Actually this is about error prevention, style and trapping. Placed 
in a tip so that it might be useful later on...

Is there anything that I've missed? What do you use as part of your 
routine? (I'm making a big check list, so that I can run every 
project against it.)


<tip type="Error Trapping" author="Frank Marion">


A list of common errors to look out for, prevent and trap...

   -> Variables
     -> Missing
       -> Initialize before it's needed, liberal use of <cfparam>

     -> Incorrect type
       -> Use logic to correctly type if possible.

     -> Incorrect scope
       -> Always keep the scope as tight as possible


   -> Paths
     -> File is absent

     -> Path is incorrectly defined
       -> If relative, use, when possible, root relative
       -> <cfparam> the root path, prefix it in all relative URLs and paths.


   -> Logic
     -> Use <cferror>
     -> Use informative error messages
     -> Keep logic as terse as possible
     -> But not at the expense of readability
     -> Favour longer variable names for clarity.
        (ie: LastYear, ThisYear, NextYear as opposed to ly, ty, ny)


When creating a form to be submitted, ensure that every field or 
attribute is declared with a default before the query is run. Use the 
default to trigger logic to clear up the problem.

Use Javascript as well as client side error checking.

When a series of transactions must occur in sequence, use 
<cftransaction> to prevent partial processes from messing things up 
(such as deleting a file, without deleting the database entry)


When attempting to update, delete or overwrite files, make sure they 
exist first. Make sure you have a course of action to take should the 
following conditions fail:
   -> A file is missing
   -> A file is locked
   -> A file has the same name
   -> A file must not be deleted (but can be, by mischance).
   -> More than one user is trying to act on the file simultaneously.
   -> A file is actually a directory


When possible, use a series of fallback actions, to accomplish the 
same task. I would imagine that more than two or three levels would 
be taxing to both the code and check writer.

Keep the code as small, and as modular as possible, for easier 
debugging. (Learned that one from Fusebox.org).


Comment madly and wisely. Take as much time and precision in 
languaging your comment as you would your code. Keep the code process 
and user process in mind when authoring it. ie.

<!--- User has clicked MyForm.Submit button.
       Ensure that Var1, Var2, Var3 are not zero length. --->


Format your code consistently. Make it an art form in clarity and 
brevity. Make it really easy on the eyes, 'cause it's very possible 
that at some point, someone will reading it at 5:00am, three hours 
before the deadline.



User Errors: It's my job to prevent the user from screwing up:

For every query that is run, if a required variable is missing or 
incorrect in some way, give the user a chance to correct it while 
saving the correct inputs, instead of simply barfing out an error 
message, telling them to use the back button.


Deal with all the missing errors at once, instead of the horrible way 
that CF does by default.

Do this:
Click: Please enter: First Name, Last Name, Phone Number. (Whatever 
is incomplete).

Don't do this:
Click: Enter First Name. Click: Enter Last Name. Click: Enter Phone Number....

Or worse
Click: (New page) "Error! *PhoneNumber* is missing. Hit 'Back' and 
correct it." (Only to find that all the info they had entered into 
the form is gone. And this happens for *every* mistake the user 
makes. (Don't laugh! I've seen it!)


When possible, auto enter data for the user.

When possible, type and format the data for the user.

Keep the interface as absolutely simple as possible, but no simpler.

Group your information and elements tightly, by related task.

Keep your language short, precise, and directive, give examples if possible.

----------------------------------------------------------------------
Enter keywords to search for: [ Text Input ] [ Perform Search ]
----------------------------------------------------------------------

as opposed to

Search
-----------------------------------
[Text Input]
[ Go ]


When an error can't be corrected by the user or logic, use 
non-threatening messages and language (ie. 'An error has occurred. 
This is not your fault. The administrator has been alerted of the 
problem and will deal with it promptly.')

</tip>


Once I've got these chops down, my next step is to deal with making 
security as tight as possible. That's another checklist coming up :P
-- 

Frank Marion                      Loofah Communications
frank at loofahcom.com               http://www.loofahcom.com