Wandering Thoughts archives

How libraries should handle internal warning messages

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.)