What we have here is a failure to communicate
Fri, Nov 14 2008 12:33
you can tell from the title there’s a Friday rant coming can’t you ? Well yeh, sometimes what should be a simple task of writing code becomes painstakingly slow. Take for example this one line of code:
Dim doc = XDocument.Load("abc.xml")
Now if you like to write robust code, somewhere in your mind there should be that voice saying, “ah but what if the file is not there or can’t be opened or isn’t valid xml “…etc, etc. So the first thing you probably think of doing is look at what exceptions the method can throw, or so you’d hope.
Problem 1. VB doesn’t display the exception information from any xml documentation. Our first failure to communicate that then leads us on a great chase.
Problem 2. Who ever wrote the XDocument.Load method actually failed to provide the exception documentation. The Load method calls external methods such as XMLReader.Create and the exceptions from that are unchecked, allowed to bubble through. The documentation should indicate an include statement to say the XMLReader.Create exceptions bubble up. The author(s) of XDocument.Load failed to communicate the exceptions that could be thrown.
Problem 3. If you like to keep current and have installed the SilverLight 2.0 SDK, F1 help will take you to a SilverLight topic even if you are writing a Console application. That little voice in your head that first said “what if …” is now screaming. There’s a failure to communicate between Visual Studio and MSDN help.
Problem 4. Your only resolve is to do the lookup in msdn help yourself, only to find the documentation has no exception information because it relies on the xml documentation (see Problem 2). The failure to communicate cascades.
Problem 5. As a last ditch desperate measure you use Reflector and walk through the code. Thankfully in this case the code is reasonably simple. The problem now is how do you get that information back into your code, so as you handle the correct exceptions ? This isn’t Relector’s fault as such, as the same problem exists if you do find the exception information in Visual Studio’s object browser. This is a failure to interact, but it can result in you not handling exceptions or documenting which exceptions bubble up from your methods, causing your code to fail to communicate. (see Problem 2.)
If religious wars were still in fashion, we’d be saying “hey what about checked exceptions al la Java ?”. The more I am frustrated at how hard it is to write robust code because of these often cascading failures to communicate, the more I want to sign up with the holly sect for checked exceptions.
An alternative is to provide rich tooling and analysis. Some years ago, myself and Geoff Appleby with some help from Mark Miller wrote a plug-in for refactor that did a look up based on the code you selected. It would match the method calls with their xml documentation, refine and sort the list based on inheritance rules (most specific first), and let you choose which ones to add to your code. It really was simple once you got the method info, which is where refactor (or more accurately DXCore) came in. Unfortunately we hosted that project on the now defunct GotDotNet site :(
Such a tool helps break the cycle here, but such a tool also needs to be used by Microsoft (see Problem 2 above), and there needs to be analysis to ensure exceptions are either handled or the documentation says what exceptions can be thrown. Writing robust code needs to be easier: we cannot just ignore exceptions.