How libraries should handle internal warning messages

March 23, 2009

The GTK libraries have a problem; using them is evidently complicated enough that programmers can commit errors that don't crash the program (partly because GTK can detect them). The people writing the GTK libraries decided that they wanted programmers to be aware of these problems, so they'd print warning messages every time they happened.

I sympathize with the GTK people, because this is a hard problem. You can't detect these problems at compile time or link time, and they're not severe enough to crash the program but at the same time you want and possibly even need the programmers to fix them. But printing warning messages all the time is still the wrong answer; the net effect is that many GTK-based applications that I use dump various 'warning' messages all over my terminal windows (if I'm foolish enough to run them without throwing away standard output and standard error). The right solution is to make printing warning messages from your library be conditional on some (non-default) environment variable.

(If you already have a logging and configuration system for your library set up, you should of course use it instead.)

I expect that the objection from library authors will be that programmers using the library won't actually turn the environment variable on, so problems in their code will go un-warned-about. However, this assumes that the programmers who don't bother to turn on the environment variable will never the less bother to notice and do something about warning messages, and I suspect that the odds of that are relatively low.

The exception to this is programmers who don't know about the existence of the environment variable. If you think that there are significant number of them, I have two suggestions. First, you should improve your documentation because clearly it is falling down on the job of educating people about the best way to develop with your library. Second, only print one or two messages from your library; one warning message, and a subsequent message about 'further warnings suppressed, set this environment variable to enable them'.

(My personal and cynical belief is that either you care about such library usage problems or you don't. If you do care you'll read the documentation and find the environment variable; if you don't you'll ignore the warnings. I may be under-estimating the number of ignorant programmers.)


Comments on this page:

From 83.145.208.36 at 2009-03-27 05:10:43:

Right on.

I have pondered with the same issue with few libraries I have worked on.

As usual, effective solutions are not novel but go far back: I really believe that the best solution is the good-old "errno"-type solution in a local context, perhaps accompanied by strongly #ifdef'd debugging messages. This should really be in some ABC of programming.

Programmers are not stupid and with proper documentation the question always boils down to "if you misuse the library, you burn". Handholding and over-verbosity is never a solution for a library, and indeed GTK is a prima facie example on what not to do in this context.

- j.

Written on 23 March 2009.
« An outline of a possibly easier IPv4 to IPv6 transition
Frustration for a sysadmin (well, for me) »

Page tools: View Source, View Normal, Add Comment.
Search:
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Mon Mar 23 00:36:00 2009
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.