Re: Fatal and unused - full text

[Sandy Harris <sandy -at- storm -dot- ca>]

Jane Carnall wrote:
> 
> There are five types of log file on the platform that we supply to outside
> developers. The fifth type is "Fatal".
> 
> The note the SME provided for it said:
> 
> FATAL - used for very serious problems that may cause the whole system to
> fall over (please don't write any code which needs this log).
> 
> I rewrote:
> 
> Fatal is used to log very serious problems that can cause the whole system
> to crash. We have not provided an example because we don't actually want you
> to ever need to use this log, or worse yet, cause us to need to use it.
> 
> (All of the other log type descriptions are provided with an example.)
> 
> I'm not sure the second sentence is necessary, but I liked it. It seems odd
> but it's certainly logical to tell outside developers that we don't want
> them find themselves using this type of log but that it does exist. Input?

I'm making some assumptions, based on what I think "fatal" means, that may
not apply in your system. What I'd write would be something like:

Fatal indicates a problem serious enough that the program cannot continue.
If it did continue, it would almost certainly crash, so it shutting down
instead. Think of the message as a suicide note from the program.

Typically, these messages arise when required resources are unavailable.
For example, an attempt to open or write a file, to allocate memory or
to start a child process can fail. If retrying makes sense in your
application -- for example if you can wait fice seconds and try starting
the process again -- then the failure is a loggable event but not Fatal.
If retries do not make sense for your application or if retries fail and
you give up, then it is a Fatal error.

For example, a program that cannot open its configuration file might
consider that a fatal error. On the other hand, it might continue
using built-in defailt settings.

Your code should use this log only for unexpected failures based on
external resource constraints. If your program cannot run because
the disk is full or someone removed a critical file, that is a
legitimate fatal error.

Please do not ever use this log for a situation where your program
cannot run because some resource it manages is fouled up. For example,
if the count of elements in an internal queue becomes negative.

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you 
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of 
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.