Step by step – The story about a code bookmarking tool
By Edward Patel
Edward is a Senior Software Engineers at Dynamo with long experience
from software projects ranging from telecom, simulation, VR, and mobile.
He has a passion for new technologies like IoT and 3D printing.
Imagine you just came into a new project. Well, say an old project but new for you. Where all of the original programmers have left the project long ago and on the scrum board there is a task to change a small feature. There might not be anyone that know the feature anymore. So, time to roll up the sleeves and jump into the code. Not much to reason about really, first thing is just trying to understand the code and all the steps that have to be made for that feature, and its current state. This has happened to me on so many occasions, and even on long projects ones owns code can be hard to remember how it works. Fresh developers might get frustrated as it is hard to wrap your head around how many ways things can be solved. Reading others code really show how differently people think and that can be scary sometimes. Those times I think entering a zen mind-state can really help. There is no spoon. But, wouldn’t it be nice if there was someone that explained all the steps that the program does to actually accomplish the feature. “We first get these things here, and then calculate Z0 here, to put it here”. But, good products live longer than people stay in the project.
Well, once I worked on a flight simulator for the Swedish Air Force. It was a simulator center with a large distributed set of simulators, 8 pilot stations and a number of radar operators and other add ons. The codebase was huge, at that time I think I heard a number like 3-4 MLOC. And there had been many many developers working on it. As it was both distributed per station it was also was distributed internally in each station. One station could be running as many as 10 to 15 separate modules. So some features could start off in one module and then bounce through a number of other modules to end up on say the radar display. How did we follow those steps? Having many windows up and just use grep and find. Basically, Blood Sweat and Tears. While working at that facility I played with the idea to have a tool that could be used to visualise the high-level steps though the code. I have seen many tools that can take code and then visualise the actual code paths, but that level is really to detailed to be easily understood. And, to be really useful I’d also wanted it to be interactive. Quick-jump into the code.
This idea has been popping up now and again for me. I have tried to see if I could easily create it a couple of times but ended it as it would have required some extra effort. Recently I happened to stumble over a simple solution for one of the things that was needed, and a couple weeks ago I got a moment to myself here at DYNAMO when I could put together this little tool. I call it CodeSteps and it is basically a kind of a bookmarking tool for code.
In this tool one can draw a set of nodes with arrows between each others, describing a sequence of event graph. Each node can be named and a specially crafted (unique) code comment is created to be copied to the code. With the use of Spotlight on the Mac it is easy to find that comment again thus making it easy to reference and jump back to just that location in the code.
The tool is actually very simple, so lets run through how to use it.
The first thing that happens when creating a new CodeSteps file is that it want to save it directly. This might seem strange, but there is a reason for that. Because CodeSteps uses Spotlight and we don´t actually want to search the whole machine, rather a folder tree for a certain project, all searches will be made from the save location and recursively deeper. So save the CodeSteps file in the root folder of your project.
To create a node just click and drag one from the boxed plus sign in the top left corner. When a single node is selected the status bar below will show from the left, a copy button, the unique comment ID, the name field, and a selected editor. **
Enter a node name in the name field and then use the copy button to copy the unique comment ID into the pasteboard for easy pasting the comment into your code. If you want you can select another editor to be used to quick-jump back into the code. When the unique comment ID have been pasted into a source code file (remember to save the file so Spotlight can index it) one can double-click the node and the selected editor should be presented with the location of the unique comment ID. Use the delete key to delete selected nodes.
Create an arrow by control-click-drag from one node to another. The arrows don’t actually do anything more than being a visual aid. Delete an arrow by control-click-drag the same arrow again.
One can also create labels on the canvas. To create a label option-drag from the boxed plus sign. Change the label text by double clicking it. Delete a label by changing the text to an empty string.
That is basically it.
Download it from here and check out a screencast on a early version below.
“The journey of a thousand miles begins with one step.” – Lao Tzu
** Currently supports Xcode, Android Studio, Atom, Sublime, Sublime 2, TextMate, Webstorm