IanG on Tap

I've recently contributed to a couple of discussions on some Microsoft blogs. The first was on Brad Abrams' blog, and was about the use of the 'I' prefix for interface names. The second was on Rob Relyea's blog, on the topic of what might be the best syntax for XAML's compound properties.

At first glance, these might seem like two unconnected ideas. One is about guidelines for naming of types in .NET class libraries. The other is about the syntax for a markup language. However, I realised that there is a common theme linking them. Actually, that's not quite right - it's more self-centred than that. I realised that there's a common theme linking the way that I happen to look at these two things. :-)

I like the convention of starting interface names with 'I'. I also like the syntax that the current (PDC) build of Longhorn uses for XAML's compound properties. (And not, as I previously erroneously called them, complex properties.) And I like them for the same reason. They both enable me to know what I'm looking at with minimal effort.

For example, suppose you had the following code snippet:

public void Frob (IFoo f)
{
  // What do we know about f right now?
}

To me, that I on IFoo yells "Polymorphism!" at me. I instantly think to myself that f could refer to pretty much any type of object, and in all likelihood a type I'm not even aware of. Indeed, someone could come along and implement IFoo after I wrote that Frob method. The effect would not be the same if the type were named Foo. My default assumption would be that Foo is probably a class, and that all Foos will behave more or less the same.

I find this only marginally useful when writing code, because the chances are I'll have to go and find out what Foo is in order to do anything. However, I find it enormously useful when reading someone else's code, either in code review, or when I have to work on code I didn't originally write. (And sometimes it's equally useful even if I did write the code, because I might not have looked at it in months...)

It's the improved readability that nails it for me. I like this naming convention because it means that an important fact about the code leaps out at me. There are other examples of this in the naming guidelines. For example, most experienced C# developers will assume that this:

foo.Bar()

is calling an instance method while this:

Foo.Bar();

is calling a static method. And all without requiring any context. Ah, the power of naming conventions! We get a similar effect with the compound property syntax in XAML - right now, when you see this:

  <Button>
    <Button.Background>
      ...
    </Button.Background>
  </Button>

you know that the <Button.Background> is definitely a compound property rather than being a child of the <Button>. So it's the same kind of idea - I am able to know what I'm looking at without first having to decode the context.

These cues are important because they minimise the amount of work you have to do to understand what you are looking at. Without these cues, you would need to have internalized a lot more about the context in which these items appear before you would know that they were compound properties (or interface types, or whatever). This is useful for exactly the same way that syntax colouring is useful - it is just easier to read syntax-coloured source code because the computer does a bunch of parsing for you and presents the results in easily recognisable but unobtrusive ways.

In short, the big win is that you don't have to devote as much brain power to working out what you're looking at, which leaves more spare for reasoning about what you're looking at. This improves your chances of making the code work, or of noticing problems in existing code.

So does this mean I want to see these kinds of cues for everything? No. That way lies madness. If you come up with some kind of adornment to make every conceivable kind of thing distinct regardless of context, you start to reduce the readability. You'll end up with what happens if you take Hungarian Notation to extremes. (Simonyi does specifically suggest not using qualifiers when they're not needed, but I've seen some projects where this notation was used well beyond its usefulness.) There are various problems with having too many distinctive cues:

1. You'll run out of cues fairly quickly. For example, you can only go so far with syntax colouring before the average person will have a hard time telling colours apart. Creative solutions to this problem tend to exacerbate the next problem.
2. Lots of different cues can make code look ugly.
3. The more cues you have, the longer it takes new developers to learn them.

This is why I don't really agree with the popular argument that this is the IDE's job rather than the job of lexical cues. If you want the cues to be visible, then it's true that the IDE can add extra cues you wouldn't get in plain text. Syntax colouring is the obvious example. But there's not much you can do beyond colouring without running into the problems listed above. So if you're going to have to stick to a small set of cues, they may as well be textual, because that way, they'll still be there if you print out the code, or open it in Notepad or vi, or when the IDE inevitably gets confused and can't work out what it's looking at either.

Of course the IDE can reduce clutter by providing info in popups. If it only shows you information when you ask to see it, it can keep the display nice and clean. In fact VS.NET does that now - hover over a symbol with the mouse, or use the "Ctrl-K, I" key sequence, and a tooltip describing the symbol pops up. This is great. It's certainly an improvement on having to work it out or look it up for yourself. But it's no substitute for the much more direct cues like colouring or lexical conventions. Popups are a valuable supplement, but when considering the speed at which a reader can take the information in, they're just not in the same class as lexical cues.

Because so much more time is typically spent reading code than writing it, there is, in my opinion, a very important place for instantly recognisable cues to tell you that you are looking at certain kinds of things. These must be used sparingly for the reasons listed above. But if the choice as to which items get these visual cues is made well, it can make it very much easier to read code, which can only be a good thing.