{"id":24568,"date":"2014-10-01T11:39:13","date_gmt":"2014-10-01T16:39:13","guid":{"rendered":"http:\/\/www.shamusyoung.com\/twentysidedtale\/?p=24568"},"modified":"2014-10-01T23:13:31","modified_gmt":"2014-10-02T04:13:31","slug":"pleasant-and-helpful-error-messages","status":"publish","type":"post","link":"https:\/\/www.shamusyoung.com\/twentysidedtale\/?p=24568","title":{"rendered":"Pleasant and helpful error messages"},"content":{"rendered":"

This was originally a commentary on the talk by Jon Blow about creating a programming language designed specifically for games<\/a>. At one point he mentions “Pleasant and helpful error messages” and I got caught up thinking about what that would really entail. So let’s talk about compiler errors.<\/p>\n

Compilers are very bad at giving us useful error messages. I’ve been doing this for decades and I still get errors that baffle me. You could make the case that “better error messaging” could be a whole project in itself. You could keep yourself pretty busy by just ditching the whole “new language” idea and just attempting to give the C++ compiler more useful output. (Although that’s probably a bad idea, for reasons I’ll talk about below.)<\/p>\n

There are errors that don’t make sense and point to things that aren’t the source of the problem. They also lean really heavy on the jargon. This is a subject near and dear to my heart. I mean, this article exists because I have this compulsion to help other people understand difficult things. <\/p>\n

Lots of people point to templates<\/a> and classes as a source of baffling messages. But rather than dive into the deep parts of the language or pick on some goofy obscure edge-case, let’s look at a really simple error:<\/p>\n

<\/p>\n

\r\n  float speed;\r\n\r\n  speed = DoMovement ();\r\n  if (speed >> 8.0f)\r\n    speed = 8.0f;\r\n<\/pre>\n
So DoMovement () sets our speed (don’t ask me what this program does) and then we attempt to limit that speed by not allowing it to go above 8. The problem here is on line 4. There should only be one > symbol there. By putting two, the compiler thinks I’m trying to bit-shift speed by eight placesThat is, move all its binary digits – all those 1’s and 0’s – to the right. It’s like moving the decimal point in a regular number.<\/span> instead of compare it to the number eight. This generates four errors:<\/p>\n
IntelliSense: expression must have integral or unscoped enum type
\nIntelliSense: expression must have integral or unscoped enum type
\nerror C2297: '>>' : illegal, right operand has type 'float'
\nerror C2296: '>>' : illegal, left operand has type 'float'
\n<\/code><\/p>\n
Okay, the first two errors come from IntelliSense<\/a> and not the compiler itself. (I think.) But that doesn’t matter for the purposes of this discussion. The point is that these messages are a very odd and obtuse way to explain these errors. This is not how a human being would describe these problems, unless they were deliberately trying to annoy you. It’s like someone saying, “The fuel reservoir has insufficient material to enable combustion” instead of saying “Your car is out of gas”. Yes, a programmer who knows what they’re doing should be able to parse that, but it’s not an optimal way to communicate. If nothing else, it’s needlessly longer<\/em>.<\/p>\n
Image unrelated.<\/td><\/tr><\/table><\/p>\n
I’m betting some coders will tell you “It’s not the compiler’s job to teach you how to program,” and “You’ll learn to recognize the error messages eventually.” But I don’t think it really works that way. I very rarely look at<\/strong> the error messages to see what I did wrong.  They’re verbose and difficult. I just double-click on the error and examine the line of code it takes me to. I don’t read the message because it’s usually a waste of time and I can spot the problem myself faster than I can untangle the addled compiler output. It’s not that experienced programmers learn to understand the compiler better, it’s that we get enough experience that we no longer need to read its output to spot problems. <\/p>\n
I don’t know. Maybe it’s me, but I never find much value in the message except to tell me where the problem is. Consider the above error:<\/p>\n
error C2297: '>>' : illegal, right operand has type 'float'<\/code><\/p>\n
A human would probably say, “You can’t bit-shift with float values.” That’s probably too<\/em> informal for a compiler, but it’s closer to useful than the one we have now. When I parse this, I stop reading when I see the phrase “right operand” and go back to looking at the code. The error message could be changed to “the right operand is a dumb butt-head loser” and I probably wouldn’t even notice.<\/p>\n
The above example is a terrible message because it doesn’t explain what it THINKS you’re trying to do, and it doesn’t say why<\/em> the operation is illegal. If you’re still thinking that you only typed one > symbol, then you’ll be baffled. What? It’s illegal to compare a float? Since when?<\/em> If the phrase “bit-shift” was in there you’d be much more likely to notice your typo, because it would draw attention to the operator instead of the operand.<\/p>\n
Image unrelated.<\/td><\/tr><\/table><\/p>\n
Having said all this, I’ll admit it’s a tough problem to solve. I don’t know who composes error messages now, but I’m willing to bet that:<\/p>\n
    \n
  1. They know the language very, very well. So well that really complex stuff can seem trivially “obvious” to them.\n
  2. They are an engineer, and were chosen for their technical prowess, not for their communications skills.\n<\/ol>\n
    It would take a ton of work, and it’s not clear what the gain would be in a purely productivity standpoint. Just saying, “It would be nicer and I would like it more” sounds like a weak justification for making sweeping changes to compiler output. It’s certainly not something people would tolerate in a mature language like C++. Giving the compiler “more friendly” error messages now would probably do more harm than good. Sure, the inexperienced would have an easier time, but the mature coders – the people currently doing real work – might have their workflow disrupted. (Unless they’re like me and read the code instead of the error.) And that’s never a worthwhile trade-off.<\/p>\n
    But I think “more readable errors” is a noble goal for a new language. <\/p>\n
    If you want to get all new-age touchy-feely, you could even have errors with optional expanded explanations that link to the language’s wiki. And then you really could have a compiler that could teach you the language. And that would be pretty cool.<\/p>\n","protected":false},"excerpt":{"rendered":"
    This was originally a commentary on the talk by Jon Blow about creating a programming language designed specifically for games. At one point he mentions “Pleasant and helpful error messages” and I got caught up thinking about what that would really entail. So let’s talk about compiler errors. Compilers are very bad at giving us […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[66],"tags":[],"class_list":["post-24568","post","type-post","status-publish","format-standard","hentry","category-programming"],"_links":{"self":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/24568","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=24568"}],"version-history":[{"count":0,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=\/wp\/v2\/posts\/24568\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=24568"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=24568"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.shamusyoung.com\/twentysidedtale\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=24568"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}