GrantRi's WebLog [MS] : Error Messages and Warnings

More on Compiler Error Messages (and their text)

grantri — Mon, 03 May 2004 17:38:00 GMT

I wish we had more UE (User Education for those not familiar with Microsoft acronyms) interaction when writing error messages. Usually, it is just a one or more devs that try and write some English (but remember we're CS or EE majors, not English or communications) that explains: what the compiler knows is wrong, why it is wrong, and hopefully the most likely way to correct it. I think this blog is sufficient proof of my English skills.

Somebody with real writing skills usually doesn't see it until a few weeks or months later when the UE teams goes to write help topics for the error message. And at that point very few UE guys understand enough of how a compiler works to properly document an error message to write a good topic not to mention improve the grammar or wording of the error message itself. UE usually rely on dev or QA to write some code that causes the error (a repro) and then more code that shows how to 'fix' the error. Then some UE are still really lost so they have dev write more of the topic, and they fix the grammar of that and publish it.

Now there have been some really good UE guys that have actually helped me (and hopefully others) write good error messages. There have also been some good devs or QAs that actually know proper English and are able to write good ones themselves. My word of advice: if you ever find somebody that understands a compiler, but for some strange reason still like writing English docs, don't ever let him go!

--Grant

A good author writes better than a good developer

grantri — Tue, 30 Mar 2004 18:39:00 GMT

So here's a recent MSDN article that I actually had the chance of reviewing several months ago. They've done a much better job at capturing the good new stuff in C# than I could ever do.

http://msdn.microsoft.com/vcsharp/default.aspx?pull=/msdnmag/issues/04/05/c20/default.aspx

I do still have a few personal corrections:

I commented that the internal names that the compiler generates have changed and will probably change again, and so the article should probably just mention that the name is compiler generated and not give the actual name (those that care can run ILDASM and see for themselves), but they didn't listen. At least they did mention that is might change. For those of you who have the community drop you'll notice that the compiler generated names have changed from what's in the article.

I also commented that using the binary tree wasn't exactly the best example of iterators because of it's miserable performance. Yes it is clean and neat code, but if you have a binary tree with 5000 nodes and you foreach it a few times, you can watch your machine crawl as it is forced to spend more and more time in the GC rather than running your code. At least they mentioned this potential problem (see the last paragraph before the Partial Types section). Too bad my brain wasn't thinking and I got the numbers wrong. It should state, “approximately n/2 iterator instantiations, where n is the number of nodes in the tree.”

Also note the small paragraph on #pragma warning that now gives you line-level control over individual warnings!

--Grant

Warning Levels

grantri — Tue, 30 Mar 2004 15:58:00 GMT

It's not documented very well, but the C# compiler actually has 4 levels of warnings. I like to think of them this way:

Level 1 - These warnings are cases the compiler is 99.9% sure you did something wrong, but the code is syntactically and semantically legal.
Level 4 - These warnings are cases where the naive user probably did something unintended, and we want to make sure they're aware of it.
Level 2 and 3 are just somewhere in between.

This seems like a pretty reasonable set, although I've often wondered if 4 levels is the right number, maybe 3 or 2 would be better. Anyway, often times we get requests from the ASP.NET team to raise or lowere the level of certain warnings. Now the whole point of a warning is that it points out a possible problem with the code. As such the compiler team has always mandated that we will feel free to add new warnings where appropriate, so those people who build with /warnaserror are just asking to be broken when they upgrade (there's a better way to do this and I'll get to it later). Now back to ASP.NET, as anybody who has used it already knows, ASP.NET does not have a way of reporting warnings. They don't go to a log or anything useful like that. Instead they build with /warnaserror turned on and the warning level set to 1. So all of our level 1 warnings become errors and break people's web sites. Anybody see the problem here?

As promisied, here's the right way to use /warnaserror: on your developer machines, before submitting changes. Then on your offical builds turn it off. Keep a warning log and send it to the developers, but don't break your build because of a warning. I don't know about your organization, but here a build break is painful!

--Grant

Error Number Trivia

grantri — Fri, 12 Mar 2004 22:24:00 GMT

Have you ever wondered how we come up with the error and warning numbers? Well if you've looked at the SSCLI source for the C# compiler, you'll see that we use a file full of macros to define the error numbers, their severity, and the resource ID that has their text (errors.h). Now like most version control systems ours has a hard time merging changes that are too close to each other. So to prevent such conflicts each of the C# compiler developers was assigned ranges, and as long as we stuck to our ranges, we never had problems. I started here at Microsoft well after the compiler was started, so I got the highest range starting at error CS1500. My most recent addition was error CS1715. Now there are some blanks or holes in the numbering. That usually comes from adding an error or warning, and then later removing it (all between releases so your lucky customers never saw it). I doubt anybody will ever go back an reuse those numbers, at least not until we run out of 4-digit numbers.

There are a few exceptions to these rules. Originally the command-line driver (csc.exe) did not share errors.h with the compiler (cscomp.dll). And that worked for a while, but became too cumbersome, so we moved it's errors into the same file and moved all of it's error numbers to start at 2000 and up. You'll also see one special error message: error CS2018. It has no corresponding resource ID. Why? Because it is the error the compiler reports when it can't find any resource DLL, and thus can't load any strings. So that one single error message will never be localized, and will always be hard-coded in the driver (csc.exe).

The last notable section are the CLS errors and warnings that start at 3000. First of all, I added most of those errors, so there wasn't much problem of merging. Secondly CLS checking was not always part of the compiler. When we did add it the Frameworks team had already written a ton of code that violated a ton of the rules. So they wanted a way to have the compiler tell them about the problems but not break the daily build. So we added special temporary switch that would force all of the errors in the 3000 range down to warnings. They used that switch until they had enough time to fix all of their code, and then we removed the switch.

How many of you ever look in the docs (inside VS or online at MSDN) for extra help on specific error messages or warnings? Our UE team likes to have a sample that reproduces the error or warning with a comment or another sample that shows how to fix it or work-around it. I personally don't think the first sample is all that useful (except for maybe setting the stage for the second sample). It just seems to me that if you've hit an error message, you don't need another sample of another way to cause the error, you just need a sample of what to do right. I am partly asking because right now the UE guys are asking me for samples for most of the new errors and warnings I've added.

--Grant

Compiler Error Messages Clarification

grantri — Mon, 01 Mar 2004 18:46:00 GMT

First of all, I am not acutally talking about decreasing or removing any errors (unless somebody can prove that a given error is a total duplicate of another one, but I seriously doubt that). I'm really talking about how big an error message can be before it should be split up. I can think of two dimensions to measure right now: the scenarios that the error message covers (how many different ways can you break a given grammar or semmantic rule and how many error messages should be used for each of those different ways); and the raw length of the error message (how much text and verbage should be put in the error message itself, and at what point should the user be forced to consult the help text or manual for clarification or futher assistance). I personally love error messages that tell you not jsut what you did wrong, but how to fix it. However in those cases I wish there was just a button that said, “fix it for me”, especially for missing semicolons, close parenthesis, and close curlys.

My other pet peeve is that fact that inside the IDE, it does not display the related locations, which as many of you have noticed, cripples some of the compiler's diagnostics. I am told that something is being done to correct that...

Thanks for the feedback on my previous post, keep it coming.
--Grant

Compiler Error Messages

grantri — Sat, 28 Feb 2004 00:30:00 GMT

I've spent a fair amount of time lately tweaking the C# compiler's error messages. At some point I begin to wonder, how clearly do we have to spell things out for end users? There are at least 2 dozen different error messages that could be summarized with just “not an l-value”. Now granted, there is an extreme. Some compilers and tools do little more than tell you an error happened, and sometimes where it happened. I believe an error message should indicate what is wrong, and if possible how to fix it. So my question for anybody who reads this an actually uses C#, do you feel like the compiler error messages are good or bad? If you can give me specific examples maybe I can get a few things fixed before we ship ;)

--Grant