Note
We are no longer accepting new customers or work orders at this time. Thank you for your interest.
The Problem
Most scripts need to display informational messages to the user - when things are going right or going wrong. To improve user-friendliness and make it easier to diagnose problems, these messages must be complete, clear, and consistent. Below we describe a number of useful tips to guide you to producing better messages.
Complete Messages
Displayed messages must be complete. Messages like this are not sufficient:
file not found.
What file was not found? Where were you looking? Why?
A good rule of thumb is, display all information related to the situation. For instance, if a file couldn't be opened, display what file you were trying to open, as well as the exact error that occurred.
A better error message would be:
someutil: cannot open file '/etc/someutil/conf' for read: file not found.
Now you also know what file, where, and what the script was trying to do (read it) at the time of the error.
Nested Scripts
Often times, one script will call another to get work done. Sometimes script-calls are nested 3, 4, even 5 levels deep. When some error occurs, such as "file not found", who generated that message? It would be nice to know which script the error came from.
Display categories
In our experience, there are 5 primary display types:
1. Errors 2. Warnings 3. Information 4. Debug output 5. Temporary debug output
1. Error message
An error message should be used when the result of this problem is fatal. The script must terminate at this point. Nested scripts will be able to make a decision based on the retuned status code. A good syntax is:
Error: message (scriptname)
2. Warning message
A warning message should be used when the result is important, but is not neccessarily fatal. The script does not terminate at this point. A good syntax is:
Warning: message (scriptname)
3. Information message
An informational message should be to tell the user about something important.
This should not be over used.
A
Info: message (scriptname)
- or -
Note: message (scriptname)
4. Debug output
A debug message is verbose output to help during debug mode.
It should not be displayed used the
Debug: message (scriptname)
5. Temporary debug output
A temporary debug message is a one time debug statement for development debug only. These statements may be turned into regular debug statements later. They should be different so you can tell them apart for other messages. If these messages are accidently left it the code, it would be obvious. We also recommend that you do not indent these lines so they are easy to location. Developers can leave them around by commenting them out. A good syntax is:
debug> message
Summary
By following these basic ideas you will save yourself a lot of headaches in the future. Other people who support and maintain your software in the future will appreciate it as well.
Privacy Policy
| Copyright © 2006 - 2010 Keith Smith Internet Marketing LLC, all rights reserved. |
| Problem with this web site? please let us know |