Consider the following bit I've just fished out of the S.MG IT troop's computers, on the basis of the ever illuminating (for the management) coffee break whine :
crystalspace.maploader.parse.meshgen: Can't find mesh factory ‘GrassLow’ for mesh generator! [node: world,sector(name=Island),meshgen(name=grass),geometry,factory(name= GrassLow) ]
This is a very bad, wrong and stupid error message for obvious reasons. The obvious reasons are that it correctly includes an indication of source (ie, maploader.parse.meshgen, which obviously enough would be that part of the maploader which parses stuff, specifically at the mesh generation point in its life) but then! it goes on to turn the message itself into... a restatement of the source. Yes yes, we know already that X is upset, thank you very much!
Imagine if your mother was in the hospital, subject to some complex, difficult surgery, and you had arrangements made with a member of the family (such as for instance an unemployed uncle) to sit there while you work in order to pay the bills for this entire amusement & distraction, on the imperative understanding and agreement that just as soon as the doctors give some results he calls you immediately.
So he calls you. You pick up. And then he goes :
"Hello, this is your uncle calling you!"
"You know, from the hospital. Where your mother is!"
"Yes, yes ?"
This is trolling, right ? I mean he did call you immediately, that part is true. However...
A good error message is very much like a letter, in that it always includes three things : an indication of the source, ie, who is sending you this. An indication of the problem, ie what has gone wrong. Finally, and just as importantly : an indication of what was being tried!
Compare and contrast :
Body : Honey, we're out of milk!
From : your ever loving slavegirl
Subject : Milk
Body : I've looked in the fridge, there's no more milk.
The first requires you to call and go "But have you looked in the fridge ?" to which you'll either get a "wait, the FRIDGE ?!" in which case you have to make a mental note for ten lashes on the bare buttocks when you get home because this is fucking unconscionable or else get a "yes of COURSE!!! I looked in the fridge what do you take me for, one of your retarded slavegirls that can't even find her way out of an empty fridge - I mean these modern ones held closed by light magnets not the old Russian models with the lock mechanism that could only be opened from outside and someone like a retarded child could suffocate inside (which has in fact happened - hence the warning thirty years ago about not locking yourself in the fridge and then dumping it in the river)" in which case mental note - fifty lashes - bare buttocks because this is even more fucking unconscionable already.
The second requires you do nothing, but allows you to go "well actually, look in the footlocker, because I was playing Fallout last night and I guess I got a little confused". And this is a good thing!
So getting back to the snippet of error log : it'd be pretty fucking great if it fucking said where it's looking!!!! as part of the complaint. Don't you find ? So we could know whether it's looking in the right or wrong place, which is to say, where the fuck does it expect to find them!
I know it should all be in the documentation. I know it's just a tee wee little bit more difficult to make the error parser aware of the path string that caused the error. But it's worth it, because it increases the magical quality of a codebase known as solidity or whatever. Which is to say, if some smart young fellow makes some change to it long after the original developer (that wasn't either as young nor as smarti) is gone, that clever change won't completely piss in the coffee of unrelated people for unforeseeable reasons. It gives an alternative to resolving problemsii, it reduces the central-point-of-failure count, it makes code less linuxy (in the horrible bad and evil sense of this term, which does exist and of which Dependency Hell is a subcircle, like the 6th).
And yes I know that in the originating example the message did correctly point to the resource in question and everything, being all helpful and whatnot. I'd like to point out that so did the uncle : he correctly indicated that indeed it's my mom that he's calling in relation to, thus eliminating the possibility he's calling about beer, or the game. Still.———
- You know that "work smart, not hard" thing ? Stupid old people work really hard by documenting all the changes they make. Young people have a lot more time on their hands and consequently know a lot better than working this hard! They work smart, see ? 'Cause they're smart and young and remember everything they did. [↩]
- Other than the "put a copy in half of the directories, then in the other half, then keep right on halving, you'll find it eventually". [↩]