This is the transcript of the video talk Better coding tools, ep02 - Stretchy code map
<< Back to index

Welcome back to this series of short talks on ideas for better programming tools. If you want a proper introduction, watch the first episode in the series. Otherwise, let's dive right in.

Idea number one: Stretchy code map. This is quite a simple little idea, but I'll still talk about it in depth so you understand the reasoning behind it. In later episodes, I'll present more and more advanced and ambitious ideas.

Imagine you're writing some new program from scratch. And for the sake of the argument, let's ignore everything not related to your own coding. So no creating new projects, version control, dependency management, build systems etc. Just you and a blank text file, ok?

You start writing code. Type type type type. You add more and more code.

As the code becomes too long to fit on your screen,

you start relying on some kind of spatial memory of what's outside your immediate field of vision. Since you wrote the code, your remember that if you were to scroll up a little from here,

you'll see the code you wrote for querying the database,

and a little further down,

you'd find that code that draws some pretty diagram.

So there is a map of some sort in your mind.

At least there is in my mind, and I assume it's the same for most other programmers too. I've always done this mental mapping, but I haven't always been aware of it. I only started consciously reflecting on it as I started thinking about better tools for programming.

Now instead, imagine that you are reading someone else's code for the first time. You're tasked with doing some changes to it, but you haven't received any guidance to the code. You have to figure it out on your own. So you're currently staring at the top of a long file.

You feel... lost, like you're in an unfamiliar big city for the first time.

You use the search feature of your editor and search for the string "password" because one of your tasks seems connected to password-related code. And you do get a search hit and jump to it, but you feel... suddenly teleported to a new street in the big city, and even more lost than before. You feel no connection between the previous screen and the new screen.

As a skilled programmer, you will eventually figure it out, but it does take some time. Piece by piece, you fill in the blanks of your mental map. If you work on this code long enough, you will map it completely and feel just as comfortable in it as in your own code.

So we want to get from "lost tourist" to "experienced taxi-driver". How could a tool help us go through this process quicker? To be clear, I don't claim that understanding the vertical ordering of code pieces is the only, or even the most important thing to understand about a new code base. Some other things which are really important to understand are for example understanding the flow of data through the program, or understanding which functions call which other functions. Those are important subjects which I want to discuss too, but in future episodes. For now, let's just focus on the map idea. Actually, let's even restrict the discussion to a single looooong function. Now you might argue that you shouldn't write long functions, you should split them up into smaller functions, and that's a whole other discussion. I have plenty of things to say about that, in a future episode.

Let's go back to our example code and try to invent some helpful visualization.

It would be helpful to see the whole function on screen at the same time. But if the tool just zooms out,

you can no longer read any of the text. You can only really see where there is whitespace or not. So what is a way around that problem? Well, the tool doesn't have to change the font size of everything equally! It could shrink some parts more than others, keeping some parts kinda readable!

Ok, but which parts should stay readable? The editor doesn't know which parts of the code you, the reader, care about right now. Should you, the reader, choose manually? No, because you're a newcomer so you don't know either! The whole point is for the editor to show you a reasonable default. Like how a zoomed-out city map will show the names of the main districts and biggest streets, but not every tiny little street name.

But wait, let's return to the argument that you shouldn't write such long functions in the first place. How would a human programmer split up a long function into smaller functions? Well, of course, that depends. It depends on the specifics of the function. But as a general observation, the splits will tend to follow the block structure aka the nesting level. So for example, if you have a function which starts with a switch statement with three cases, and inside each case there are many pages of code, a human programmer might take all the code inside case A and extract it to a separate function, and then take all the code inside case B and extract that, and so on. This ought to give us some inspiration.

I suggest that the map should zoom the font size based on the level of nesting. I mean the logical structure of blocks inside blocks. So the outermost code gets the biggest font size, and the most deeply nested code gets the smallest.

The precise zoom levels should be automatically adjusted so that the whole function fits vertically on your screen - no scrolling required!

I made a quick mock-up of this idea with html&javascript.

And I like it. When I need to read a function for the first time in my programming job, I think I would prefer this view over the typical view of just seeing the top few lines of the function. I'd say that this gives a nice overview from the outside in.

But now let's think about that situation where you've searched for the string "password" in this long unfamiliar function, and you've been teleported to somewhere in the middle of the function, maybe in some deeply nested block.

Now you have a different problem than before. You no longer want an overview from the outside in. Now you're probably more interested in your immediate surroundings. So even though you're in a deeply nested block, you want bigger font size around you.

At the same time, you also want to know where you are in the greater structure, aka context from the inside out. So in our unfamiliar city analogy, you would want to know that you are on this street, in this district, which is on the east side of the river, and so on. To explain this, I assume you who watch this video is familiar with the terminology relating to trees in computer science. We have to look at the active line in the text editor. Which blocks is the active line inside? Maybe it's inside the body of a while-loop, which is in turn inside the body of an if-statement, inside another loop, and so on.

I believe you'd be especially interested in the line with the while-condition, aka your parent, and the line with the if-statement, aka your grandparent, and so on. I think all the ancestors, all the way up to the root, are interesting and should thus have a bigger font size. Your ancestors' siblings are less interesting, and your ancestors' siblings' children are even less interesting.

So I think a map should show both overview from the outside in,

and context from the inside out.

As you, the programmer, move around in the function, the map will of course have to change, dynamically. The change mustn't be too radical and sudden, because that would feel disorienting, again like being teleported. So the change has to be gradual and smooth.

So now we have reached the present day. What you're seeing on screen is the current version, my latest version of this new map idea.

Now that we have this view, how do we integrate it with the rest of your development environment?

Well, making it tall and thin, like the minimap in Sublime Text or Visual Studio,

wouldn't work well because the lines with large font size will also get quite wide and thus get cut off. But if you have a large monitor or several, maybe you're willing to give up some more screen real estate to this new map.

Or alternatively, maybe it's not a split panel, maybe it's a mode you toggle on and off. So from your normal text editor, you could hit a hotkey and switch the view to this map-mode, navigate to somewhere else, then switch back. I'm not sure which kind of integration is best...

Which version do you prefer? You can try them yourself, there are two links in the video description.[0] [1] Just to calibrate your expectations, remember that it's just a prototype, so the code behind it is not optimized, and you can't actually use it with your own code in any real text editor today. I'm showing the idea to get constructive feedback, and to inspire others to think outside the box. I plan to implement this at some point, but it's gonna take years, because I have so many other projects too.

If you found this interesting, please let me know, it will motivate me to make more episodes and more prototypes. Thanks for watching.