Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]
| From | Ian Collins <ian-news@hotmail.com> |
|---|---|
| Newsgroups | comp.lang.c |
| Subject | Re: Mechanism to generate annotated "error codes" |
| Date | 2012-03-05 20:46 +1300 |
| Message-ID | <9rj9aoFi9oU1@mid.individual.net> (permalink) |
| References | <jiojq3$3cm$1@speranza.aioe.org> <9ri412FadbU2@mid.individual.net> <jj0scq$ckd$1@speranza.aioe.org> <9rifh9FadbU5@mid.individual.net> <jj1igi$oae$1@speranza.aioe.org> |
On 03/ 5/12 06:21 PM, Don Y wrote: > Hi Ian, > > On 3/4/2012 5:26 PM, Ian Collins wrote: > >>>>> I have a suite of projects that utilize a common approach to >>>>> error reporting. Instead of a PASS/FAIL result, most functions >>>>> return information regarding the nature of the "failure" (which >>>>> can also include "partial failures"... "warnings"). These >>>>> reports allow upper levels of the application to convey those >>>>> details to the user without exposing all of the *mechanism* >>>>> involved to those upper levels. >>>> >>>> My usual technique for this class of problem is to build the tables in a >>>> programmer and machine friendly format, typically XML in the guise of an >>>> Open Office document. >>>> >>>> The programmer(s) can easily maintain and version control the document >>>> and the machine can easily perform validation of the data (one of my >>>> teams developed an XML schema validation tool for this purpose: >>>> http://sut.sourceforge.net) and generate the necessary headers. >>> >>> Yes, but now you have to manually relate the messages to the >>> code from which they were "reasoned". It would be like keeping >>> the *comments* for your source code in a MSWord document (i.e., >>> sure, you could *do* it but you KNOW the two documents will >>> quickly get out of sync as pressure has you updating one and >>> defering the effort of updating the other). >> >> Not at all. >> >> First the user or log messages have to be documented somewhere, for user >> documentation and testing. > > Yes. I document them IN THE CODE. > >> Scattering them throughout the code isn't a >> great way to do that. > > Why? Because it is easier to generate code than it is to parse code and extract information from an entire code base. It is also easier to maintain a single document in a form that can be translated in to things other than code (especially if you have a need to get some of the messages translated). > It ensures EVERY error code is documented. And, it keeps that > proximate to the actual code itself. *This* is what the code is > testing for... not something else that you THINK it is enforcing! Quite. The table of error codes/messages/whatever is all generated from one place. If a new error code is required , it has to be added to the master file. >> Second, the document is the *source* for the messages and error codes, >> so it will always be up to date. > > What happens when an error code is never referenced? How does > your document ELIDE that error code and its documentation? Nothing. How many of the error codes in a typical system header (such as <errno.h> on a Unix system) does any one application actually use? If new errors are added to the master file as required, this will not really be a problem. >>> E.g., the approach I am taking here is analagous to how Literate >>> Programming couples documentation with source code (except I am >>> only tackling the "error reporting" aspect of the task). >> >> In my case, the documentation *is* part of the source code. > > Fair enough. You should look at Literate Programming for a > different take on this (see URL later) We did, however code editors tend to be piss poor word processors and word processors tend to be piss poor text editors! It's quite easy to write code in Open Office and extract the code sections for compilation, but it's a process not well suited to contemporary tools (IDEs). On the project I mentioned, the master XML was used to generate many different components, including database tables and their equivalent C structures and enumerations. So this file had a lot more value than it would had it simply been used for error codes and messages. Elsewhere in this thread someone mentioned a function to check input values, well the types and range of common data types were also specified in this file, so all the range checking and error reporting was centralised. >>>>> A "solution" also needs to address the problem of *explaining* >>>>> the "result" (to the ultimate user). The point at which the >>>>> result is "signaled" contains the most information about the >>>>> nature of the "problem" being reported though it is in a >>>>> very narrowly defined context: i.e., you can tell the user >>>>> "Multiple decimal points encountered" -- though you can't >>>>> indicate the role that the value being entered plays in the >>>>> application (is this a person's wages? the weight of a >>>>> newborn child? the average lifespan of a male tortoise?). > >>>> Tables in an Office document are ideal for this. You can include as much >>>> information is you want, Your code generation can select various subsets >>>> of the data to present as user messages. >>> >>> I extract the error code, short message and long message (as well as >>> the locale indicator) and stuff those into a (real) database >>> (you could just as easily create a big array of struct's and >>> index/search that based on the "(error code, locale)" presented). >>> >>> This moves all that "text" out of the "TEXT" section of the program >>> (it could reside on a different *processor*!). It also lets someone >>> non-technical make and review translations without having to understand >>> the actual code surrounding it (though the code acts as the final >>> arbiter of what the error message actually *should* convey). >> >> Our approaches appear to be opposite. You extract messages from the >> code, I inject them into the code (and the tests and user documentation). > > Fair enough. My approach is "inspired" by Literate Programming > (http://en.wikipedia.org/wiki/Literate_programming). In either > approach, you need to have a tool/utility massage a file (or > files) to generate the actual "source" and supporting files. I believe the the tools required to generate code from XML are much simpler than those required to extract documentation form code (other than from code comments). > I bundle it in the source because I can just let MakeErrorCode > be a macro that doesn't alter the source (Literate Programming > requires the source to be "extracted" -- "tangled"). But it doesn't solve the uniqueness problem. With a master file, you don't have to worry, or even define the error values. The translator can do that for you. -- Ian Collins
Back to comp.lang.c | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread
Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-01 12:48 -0700
Re: Mechanism to generate annotated "error codes" Willem <willem@toad.stack.nl> - 2012-03-01 21:29 +0000
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-01 16:53 -0700
Re: Mechanism to generate annotated "error codes" William Ahern <william@wilbur.25thandClement.com> - 2012-03-01 14:13 -0800
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-01 22:07 -0700
Re: Mechanism to generate annotated "error codes" Shao Miller <sha0.miller@gmail.com> - 2012-03-01 17:53 -0500
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-01 23:05 -0700
Re: Mechanism to generate annotated "error codes" Shao Miller <sha0.miller@gmail.com> - 2012-03-02 01:50 -0500
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-02 00:43 -0700
Re: Mechanism to generate annotated "error codes" Shao Miller <sha0.miller@gmail.com> - 2012-03-03 17:58 -0500
Re: Mechanism to generate annotated "error codes" Shao Miller <sha0.miller@gmail.com> - 2012-03-04 03:16 -0500
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 13:47 -0700
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 13:45 -0700
Re: Mechanism to generate annotated "error codes" Shao Miller <sha0.miller@gmail.com> - 2012-03-04 18:37 -0500
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 22:12 -0700
Re: Mechanism to generate annotated "error codes" Shao Miller <sha0.miller@gmail.com> - 2012-03-08 01:41 -0500
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-09 14:34 -0700
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-02 00:30 -0700
Re: Mechanism to generate annotated "error codes" Keith Thompson <kst-u@mib.org> - 2012-03-02 02:05 -0800
Re: Mechanism to generate annotated "error codes" Kaz Kylheku <kaz@kylheku.com> - 2012-03-02 10:47 +0000
Re: Mechanism to generate annotated "error codes" gazelle@shell.xmission.com (Kenny McCormack) - 2012-03-02 14:18 +0000
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-02 10:46 -0700
Re: Mechanism to generate annotated "error codes" James Kuyper <jameskuyper@verizon.net> - 2012-03-02 14:08 -0500
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-02 12:38 -0700
Re: Mechanism to generate annotated "error codes" Kaz Kylheku <kaz@kylheku.com> - 2012-03-02 22:57 +0000
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-02 17:14 -0700
Re: Mechanism to generate annotated "error codes" Kaz Kylheku <kaz@kylheku.com> - 2012-03-03 02:25 +0000
Re: Mechanism to generate annotated "error codes" James Kuyper <jameskuyper@verizon.net> - 2012-03-03 06:10 -0500
Re: Mechanism to generate annotated "error codes" Shao Miller <sha0.miller@gmail.com> - 2012-03-03 16:12 -0500
Re: Mechanism to generate annotated "error codes" Keith Thompson <kst-u@mib.org> - 2012-03-03 04:04 -0800
Re: Mechanism to generate annotated "error codes" Kaz Kylheku <kaz@kylheku.com> - 2012-03-03 15:05 +0000
Re: Mechanism to generate annotated "error codes" Ben Bacarisse <ben.usenet@bsb.me.uk> - 2012-03-03 16:25 +0000
Re: Mechanism to generate annotated "error codes" Shao Miller <sha0.miller@gmail.com> - 2012-03-03 16:26 -0500
Re: Mechanism to generate annotated "error codes" Keith Thompson <kst-u@mib.org> - 2012-03-03 13:40 -0800
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-03 12:03 +1300
Re: Mechanism to generate annotated "error codes" Keith Thompson <kst-u@mib.org> - 2012-03-02 15:45 -0800
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-02 17:18 -0700
Re: Mechanism to generate annotated "error codes" blp@cs.stanford.edu (Ben Pfaff) - 2012-03-02 15:08 -0800
Re: Mechanism to generate annotated "error codes" "BartC" <bc@freeuk.com> - 2012-03-03 10:30 +0000
Re: Mechanism to generate annotated "error codes" James Kuyper <jameskuyper@verizon.net> - 2012-03-03 06:19 -0500
Re: Mechanism to generate annotated "error codes" Phil Carmody <thefatphil_demunged@yahoo.co.uk> - 2012-03-03 15:15 +0200
Re: Mechanism to generate annotated "error codes" Kaz Kylheku <kaz@kylheku.com> - 2012-03-03 14:52 +0000
Re: Mechanism to generate annotated "error codes" Malcolm McLean <malcolm.mclean5@btinternet.com> - 2012-03-03 07:39 -0800
Re: Mechanism to generate annotated "error codes" Jonathan Leffler <jleffler@earthlink.net> - 2012-03-03 23:56 -0800
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-05 09:20 +1300
Re: Mechanism to generate annotated "error codes" Malcolm McLean <malcolm.mclean5@btinternet.com> - 2012-03-04 13:28 -0800
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-05 10:56 +1300
Re: Mechanism to generate annotated "error codes" "BartC" <bc@freeuk.com> - 2012-03-03 17:02 +0000
Re: Mechanism to generate annotated "error codes" Keith Thompson <kst-u@mib.org> - 2012-03-03 12:30 -0800
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 19:15 -0700
Re: Mechanism to generate annotated "error codes" Kaz Kylheku <kaz@kylheku.com> - 2012-03-04 03:20 +0000
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 11:03 -0700
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 16:31 -0700
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 23:04 -0700
Re: Mechanism to generate annotated "error codes" Malcolm McLean <malcolm.mclean5@btinternet.com> - 2012-03-02 22:13 -0800
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 00:49 -0700
Re: Mechanism to generate annotated "error codes" Malcolm McLean <malcolm.mclean5@btinternet.com> - 2012-03-03 03:32 -0800
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 12:04 -0700
Re: Mechanism to generate annotated "error codes" Lowell Gilbert <lgusenet@be-well.ilk.org> - 2012-03-03 15:06 -0500
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 14:38 -0700
Re: Mechanism to generate annotated "error codes" Malcolm McLean <malcolm.mclean5@btinternet.com> - 2012-03-03 12:15 -0800
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 16:51 -0700
Re: Mechanism to generate annotated "error codes" Malcolm McLean <malcolm.mclean5@btinternet.com> - 2012-03-04 14:08 -0800
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 15:56 -0700
Re: Mechanism to generate annotated "error codes" Malcolm McLean <malcolm.mclean5@btinternet.com> - 2012-03-03 03:45 -0800
Re: Mechanism to generate annotated "error codes" Lowell Gilbert <lgusenet@be-well.ilk.org> - 2012-03-03 14:11 -0500
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 13:03 -0700
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 12:32 -0700
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 15:04 -0700
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-04 11:09 +1300
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 16:55 -0700
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-04 13:04 +1300
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 18:24 -0700
Re: Mechanism to generate annotated "error codes" Malcolm McLean <malcolm.mclean5@btinternet.com> - 2012-03-03 14:30 -0800
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-03 17:06 -0700
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-05 10:09 +1300
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 16:03 -0700
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-05 13:26 +1300
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-04 22:21 -0700
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-05 20:46 +1300
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-05 10:54 -0700
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-06 10:02 +1300
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-05 16:09 -0700
Re: Mechanism to generate annotated "error codes" "BartC" <bc@freeuk.com> - 2012-03-06 10:54 +0000
Re: Mechanism to generate annotated "error codes" Ian Collins <ian-news@hotmail.com> - 2012-03-07 07:22 +1300
Re: Mechanism to generate annotated "error codes" gordonb.8sa24@burditt.org (Gordon Burditt) - 2012-03-06 08:51 -0600
Re: Mechanism to generate annotated "error codes" Don Y <this@isnotme.com> - 2012-03-06 11:21 -0700
csiph-web