The Mindset

Here’s the deal. You find yourself in a city you do not know. How did you get there? You don’t know. It is just as if you were dropped in the middle of this foreign city by aliens. No one around seems to speak your language. Everywhere you look you see roads, buildings, cars – artifacts you know, but they don’t mean anything to you in that particular context.

So, like a good survivor, you decide that staying in one place is not a good idea. Night will be falling soon, and you need a place to stay. Luckily, you alien friends left you with an international credit card. Without any better idea, you start walking.

Street after street, block after block, building after building you become more and more frustrated. You probably knew you were shooting in the dark, but after five hours of walking the possibility of not finding a place for the night seems more realistic.

You are that close to being desperate, when suddenly you notice you have a piece of paper in your pocket. It’s an aerial photograph of the city you are in. Of course you cannot know that for sure, but you find it encouraging anyway. The photograph is even annotated with the text “You are here!” pointing at a specific location in the city.

“Cool. I’ll go back to where I’ve started, and then I will know exactly where I am”, you think. Luckily, you have a great memory, so five hours later you arrive at where you’ve started. Thank God! Now you know exactly where you are. Great. That was close. Wow.

“OK. Now, let’s find a place to have a bite and rest for the night”, you say to yourself. Let’s hit the road. Well… what are you waiting for?

A couple of minutes later you realize that while you certainly “know” where you are, you still don’t have a clue as for where you should be going. The state-of-the-art photograph you have might be great for many things, but it won’t help you find your way to a cozy hotel room. 

You wake up. Your head hurts as if you’ve just slept for two hours on your keyboard (which is exactly what happened). Wow. That was some dream. Well, back to work… what were you working on…? Oh, it was THAT project again. The project that was just assigned to you and requires some emergency fixes. The project which was written by some developer who was in a hurry for his next job. OK then, were should you start?

You gaze at the code, but this doesn’t seem too productive, so you start reading it. Component after component, class after class, method after method you become more and more frustrated. A strange deja-vu feeling is starting to get over you.

Maybe it will be easier to start at a higher level, you think. Luckily, you can reverse engineer the code using a state-of-the-art modeling tool, so within seconds you have an accurate picture of the project. Great! Now what? You know where you are, but you have no clue as for where you should be going…

***

It doesn’t take an extremely big project to make you feel lost. Especially if you were not part of the original team who wrote it. Believe me, I know the feeling. Sure, it all turns out well at the end (in most cases). But the time and energy you spend in order to get there are extremely frustrating.

Reverse engineering the code doesn’t improve things much. There is so much implicit knowledge which should have helped you understand where you are going. But none of it can be found in an auto-generated map of the code.

Now for the good news. None of this is a will of God or a law of nature. Things can really be different.

Think of what would have helped you to find a nice little hotel room, or a good restaurant, in that foreign city. First, you probably don’t need all the details provided by the high-resolution map. What you do need, however, is some useful annotations and guidelines. Some implicit information, which cannot be seen from the air, to guide you through the infinite maze of streets. If, for example, the map would have contained a pointer to the hotels’ area, you could have started walking in the right direction.

Having a high-level annotated map of the code reduces maintenance costs.

Don’t settle for a UML diagram listing all code entities. UML alone will not do the trick.

Create a set of diagrams with various resolutions, various level of details, and different parts of the code. Some of them should describe static aspects of the code, while others should focus on dynamic aspects.

Choose carefully what to include in each diagram. Think of the details that will be useful for a developer new to your code. Don’t reverse engineer the code to produce a diagram with each and every little detail.  

And most important, make sure to write down implicit knowledge, such as the role of code entities, implicit assumptions used in their interactions, etc. UML diagrams are not enough. Write down what you would have told a newly assigned developer had you met him face to face. Write in plain English.

Try to explain what led you to important design decisions: what were the considerations that shaped the design to its current form. Such background knowledge is important in order to make sense of the design, instead of treating it as a set of arbitrary decisions.

Don’t try to capture each and every little detail. Think of this document as a road map that will guide a developer in his first steps in your code.

This is not easy. You have to put yourself in the place of that developer. If you find it hard, pick a developer who wasn’t involved in the project and let him try to find his way through the code using your annotated guide. Watch him to identify the areas he is having troubles with, and fix your document accordingly.

Don’t make your successors feel lost in your code.

This entry was posted on Tuesday, May 30th, 2006 at 11:46 am and is filed under Design, Communication, Documentation. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.