A few years ago one of the first books I’ve read when I started learning Ruby was the ‘Build Awesome Command-Line Applications in Ruby’ by David Bryant Copeland. It’s not like I build command line apps every day (and it’s not like those I’ve built are in any way awesome) so I don’t remember much of it now. One point got firmly stuck into my mind though: applications should play well with others.

On the command line, an app that “plays well with others” is an app that can be used easily by other apps directly or indirectly, alongside other apps, on the command line.

He also expands on it in his blogpost.

An app that “plays well with others” on the command line, basically means that it acts as a filter. Text comes in, gets processed, the processed text goes out. The expectation is that text from any other “well playing” program can be input into our program, and that our program’s output can be piped into another program as input.

An issue with TypeScript, a fairly awesome project in many ways, got me thinking about it again. This is a story of a simple design decision.

What’s going on?

Typescript package includes a command line tool for building js files from typescript. It’s called tsc and of course it comes with the ‘watch’ mode for continuously building your project on file save.

What you might find is when you start it with tsc -w your console gets cleared.

The good?

Clearing console seems a nice touch. I mean, let’s make it neat and tidy — you’re gonna be looking for error messages and such, right?.

Then every time a file save leads to a project recompilation the tsc is gonna clear the console again. Which is a nice touch. I mean, you probably wanted the most recent output anyway, right?

The bad

These kinds of design decisions are cool, fresh and focused on user comfort. The issue is they’re based on assumptions which aren’t necessarily correct.

People want important stuff to be at the top of their terminal.
Fiddling with console is ok.

Both of those are false.

I don’t know about you but my experience trained me to look at the bottom of the terminal anyway. I don’t think shaking up my output is helpful, but who knows, that may be just my Stockholm syndrome talking. Also, clearing terminal rings a bell. Literally, if you use xterm, your terminal will annoyingly notify you by showing a bell and its icon jumping in dock.

So by now we have a supposed improvement at the cost of causing mild annoyance. Not terrible by any means, but not a great look either.

The ugly

Things get really rough when you use tsc in watch mode together with something else. What kind of ‘something else’, you ask?

I have a back end. There’s probably a sinatra instance running.
I have my styles written in sass, so there’s a sass compiler watching for changes.
God knows what else I have running in background, but I’m probably using some tool like foreman to make sense of it all.

The “we’re gonna clear your console for you” approach just isn’t working anymore. tsc mangles my output and it becomes a complete mess.

Now to be fair, it’s 2019 and this doesn’t happen with webpack-dev-server as the server uses its own mechanism for watching filesystem changes. But webpack is not an end all be all tool. There are projects where it doesn’t make sense to use it. It just seems weird to be having these problems with the bare bones version.

The standoff

I have to acknowledge that it took TypeScript team only a month and a half and several github issues worth of bashing from the community to add a --preserveWatchOutput flag for what should have been the default behaviour all along.

$ tsc -w --preserveWatchOutput

Of course, the audience of developers will always find a way (folks came up with pretty cool sed and awk workarounds and even a package). And the TypeScript project is overall pretty great, so this minor hiccup is of course not enough to turn the community away.

It still is a useful design case though. And its main takeaway is, “Don’t surprise us”.

Should we all be boring then?

No way! I hear you, we must take risks to find better solutions. We might upset someone, but it’s all worth it when we’re changing the world! One compiler at a time.

Well, look, it’s all about user centered design. As always, the product you’re designing needs well-defined personas. And the personas of software developers really don’t like being surprised.