Tom MacWright

Redesigning Istanbul

Recently I contributed design improvements to Istanbul, the most popular code coverage tool for JavaScript. Starting with version 0.4.0, all new HTML reports will look a bit nicer.

The place that low-level code like Istanbul occupies in the open source landscape makes it fascinating: its popularity is a long-term ramp and there’s little in terms of embellishment of the codebase: it’s all core.

It’s also a fascinating process to redesign open source projects. Contributions like this are almost done as Pull Requests on GitHub. Contributors, onlookers, and maintainers follow along with a set of changes and all of them can add to the long list of comments and suggestions that lead up to the final acceptance or rejection.

Design reviews on GitHub are quite different than code reviews: it’s much easier to review and react to a design than it is to read hundreds of lines of code change. There’s also aesthetic leeway in design and ‘one more change’ before it’s perfect.

It’s harder to contribute design to an existing project than it is to greenfield or to redesign a project you control. Especially for a design that’s clearly time-limited, like a side-project, it’s very important to scope and communicate around it: in this case I applied past experience to specifically call out the scope. No changes to Istanbul JavaScript internals, no substantial changes to page information hierarchy, no attempt to systematize CSS or move toward a framework. Explicit limitations are what make projects finishable.

The Istanbul redesign went really well: the comments were mainly constructive and descriptive enough to be implemented. Any time-worn design has elements that go against convention but fit some corner case, and this one has a few, like the lack of a width-limiter making it possible to see long filename paths in big projects.

Once you adopt Istanbul, you’ll use it hundreds of times: running and re-running tests to confirm that every branch and statement is covered. This redesign makes that experience just a bit more pleasant.