Naming is Hard, But Worth It

I got a design review recently where a Quux, which has a field we'll call Foo, was supposed to get a new field called FooSource.

You don't need to know anything about the code or the rest of the design, for the name to start you thinking.  I noticed that word "source".  Why should an object need to know where something comes from?

What might the values of FooSource be, in practice?  They would have to identify the possible sources of a Foo.  That is, they would contain information about the rest of the system; about the various places in the rest of the system that a Foo could come from.  If the system changed such that a previously valid source of Foos no longer existed, we'd have to go through all the Quuxes and fix the ones that pointed to the now-defunct source.

Also, up to now we've kept the module of code that Quux belongs to pretty clean; it doesn't have any code dependencies on the upstream part of the code that knows how to make a Foo.  So if we wanted to validate FooSources at compile or run time, we'd need to introduce a new dependency.  Someone who changed the code that makes Foos would have to rebuild, and republish, the Quux code.  If my team owns Quux, that means that whenever the Foo team does a release, we have to stop what we're doing and spend a few weeks making sure that we're in sync.

Eventually we concluded that FooSource should live in a separate module whose purpose is to define the overlap between Foo and Quux.  That module will have to be maintained whenever Foo changes; but it is a small and simple module whose sole purpose is to define that interaction, so it's easy to test and safe to change.  The Quux module will remain clean.

As a side effect, I learned that I've not done a good job communicating our high-level architecture to all my developers.  So I've got some homework to do, making and presenting better architectural documentation.

The bottom line here is that the developer who chose "FooSource" as a name did a good thing: he communicated his idea.  The idea was flawed, and we fixed that; but if it hadn't been for the clear, descriptive name, I wouldn't have realized what it was he was trying to do, and the error would not have been caught till it was too late.  It's hard to boil a complex idea down into a dozen or so characters, but it is very, very valuable.