Blogging Ottinger (tim)

What do you do when you’re in a new project, and you’re sitting with a requirement in your hand and an unfamiliar code base in front of you? Navigation is a tough game. One can spend a lot of time just trying to find the place in code where the work is to be done, and then finding the tests which are relevant to the change being made. Even with some help, it can take some time.

Sure, if all the code is yours, navigation is trivial. You know where to go without thinking about it — you’ve internalized the entire design and probably much of the code base. You know where it is done, how it is done, and the names of all the participants. The tests are obvious and the code is trivially easy to read. But to the outsider, naming seems somewhat arbitrary and structure is inobvious. It’s the non-internalized condition. It really doesn’t matter how good the code really is, it’s how it seems.

In Are Your Lights On?, G. Weinberg said that a problem is the difference between things as desired and things as perceived. Therefore we can either change your perception or your desires, or change the way things are (or some combination of the above).

Let’s take a poor example (for illustrative purposes only) and see if we can’t see a few different positive possibilities.

In our example, a homemaker puts forks and spons in seemingly random places in the house. They all make sense to him, but they are found in ones and twos in magazine racks and bookshelves, cabinets, refridgerators, television stands, etc. The homemaker knows exactly where every one is found, and can prepare and eat meals in comfort. An observation is that the implements are placed in a way that makes it hard for a visitor to find them. That is just a fact, neither an accusation of the homemaker nor a slur on the intelligence of the visitor. Just a fact. Lets start there.

Certainly, one can blame the implement-finding difficulty on poor organization, but it may be perfectly reasonable. Perhaps the measuring implements are close to the supplies which need to be measured — in the pantry, in the cabinets, etc. Or some large measuring tools are kept with large storage and cooking dishes, whereas small measures are kept with food items used more sparingly (cinnamon, for instance). The items used primarily for eating ice cream are stored in the homemaker’s living room, where his ice cream is usually consumed (in front of a TV). So it is neatly arranged according to use. In this case, the visitor is only confused because the system is unfamiliar, and the visitor could learn the system behind it given sufficient time. This is rather like the expert-friendly editors (vim, emacs, etc) which are uncomfortable until one has paid his dues by memorizing enough of the commands and command structure to become proficient. Such a system can be quite comfortable to one who is proficient. Code can be arranged in a way that is convient for some and not for others.

One could blame the homemaker for making the system novice-hostile. It is an idiosyncratic arrangement, and out of the norm. Usually serving utensils are kept together, table utensils are kept together, and measuring utensils are kept together. Often these are three different places all in or near the kitchen and dining room. This is what one would expect to find. Having flatware all over the place makes it hard to find the parts you want, and hard to put them away after washing. A commonly-used arrangement is more pleasing to the novice, but may be less well-tailored to certain ways of doing things.

Now, the homemaker could put all of the flatware (serving, measuring, and table-ware) in the same drawer, and that would make it a mess, though it would be easy enough to learn the system. It would be easy to put them all away after washing, too. But it’s not the normal mechanism, though it’s simpler. It’s not optimal, though, because one has to dig out the measuring tools from among the rest when cooking. Then he must dig out the serving utensils to put the meal on the table. After that, he must dig out the table utensils from among the jumbled mess. It’s hard to tell if you have enough tableware to seat 4. Some simple ways are worse.

Probably the best thing for a novice is to keep patience and try to learn the system in use. It could be excellent, it could be horrible, but when you don’t know what it is you can hardly judge which it is. It could be very carefully planned and orchestrated for special use, or may be oversimplified. It’s hard to tell. It’s not the time to write off the code as poorly organized, nor yourself as a slow learner. It may just take time.

The least productive thing is to criticise the productive team already in place. After all the goal is to join them and learn from them. Joining late requires humility and patience from everyone. Being disrespectful or accusational simply doesn’t pay. Besides, the haughty man is the man who thinks he has nothing left to learn.

In dealing with unfamiliar code what is needed is just some basic backgrounding and some experience taking advantages of the navigational aids. And more self-control and maybe more rest. Impatient people spend a lot of time being frustrated, and being frustrated is exhausting. Just ask me, I know.

May we be granted equal parts courage, patience, and wisdom.