A couple of days ago I wrote about sonifications, the sound equivalent to visualizations. Even though they haven’t permeated business culture in the same way visualizations have, they are around us used in a folk way—meaning, designers use sound in their interfaces, but it isn’t systematic or directly supported in tools.

Even without that discipline, sonifications generally do a much better job of making themselves actionable. This is because that’s the main reason you use sound. You need to interrupt the user and get them to do something now. In my last essay on this topic, I gave a list of examples you encounter while driving: car honks, sirens, lane-drift warnings, etc—they all need immediate attention.

If we look at visualizations we encounter while driving, actionability is a core-driver. The gas light, tire-pressure warning, traffic lights all translate to simple actions. Even the check engine light wants you take an action (which is true even if you ignore it).

A lot of visualizations I see elsewhere aren’t that clear. It’s easy to make charts in most software that has data, and the easiest thing to do is to pick a chart template and populate it. It practically makes itself.

The problem is that many visualizations are communicating the list of data and not the action. Instead of random lines going up and down periodically, I want a green or red light*. And just like in my hometown of Queens, if I don’t pay attention to the light, a honk.

---

* Augmented for color-blindness and accessibility, of course

I cringe when I hear a GUI described as “ugly”. It’s not that I don’t see it too, but the feedback isn’t helpful. I can’t set the ugliness lower.

If something looks “ugly” to you, use that to guide your attention and analysis. What we often perceive as ugly is rooted in rules of perception and communication.

To give you an idea, considering just the visual look of a design (not its interactions), try to judge

• How easy is it to see the entire UI as various levels: as a whole, as a collection of a few parts, at a detail level.
• How quickly can you scan and visually acquire a component.
• How correct is your intuition on how a component would work based on what it looks like
• How easy it is to tell things apart.
• How easy is it to group things

Then, try to express you critique as: this “attribute of the design” doesn’t accomplish “this specific communication goal”

Here are some examples of what I mean:

• The button icons aren’t easy to tell apart so they are hard to find right away.
• The buttons need more padding because the text is too close to the border, making it harder to read.
• I can’t tell the difference between the various header levels
• The colors of the icons don’t feel like they come from a unified palette. Let’s try to match their saturation and brightness levels.
• It isn’t clear if this visualization means that the state of the system is good or bad — it needs more context
• There isn’t enough contrast between the most important parts and rest of the UI
• There isn’t enough whitespace helping to form a hierarchy of information
• The spacing between paragraphs isn’t proportionate to the font and line height. It makes it harder to read the text.

Look at the visual variables: colors, values (lightness/darkness), sizes, positions, and shapes. Consider whitespace. Look at the relationships between the components.

Consider if there is too much or too little contrast. Is there harmony between things that are supposed to be the same? Do the most important things draw the eye? Can you scan?

These are just the surface level. Bad UIs are usually bad at a level deeper than that. But if it looks “ugly”, expressing that as contrast/harmony of visual variables is more actionable.

On my first day at Trello, my peer mentor showed me two things. One of them ended up being the topic of my talk on Reactive Programming. The second thing he told me was, on our team, PR’s should tell a story.

Then we pair constructed a PR. To be clear, he was already in a local branch, and the code was already written and committed.

He showed me how he used git reset and git rebase to rewrite the commits. He explained that he was rebuilding the commits to make the PR easy to review. He constructed each commit to be atomic—to do a single coherent thing.

This was the PR style for our team for the whole time I worked there. The goal of a PR was to make it easy to review, and we expected reviewers to open each commit in a tab and review them one-by-one. We considered it acceptable to decline a PR if it was too big or hard to review (in practice, this happened very infrequently).

Other practices:

1. PR’s were mostly less than five commits. If they were more, it was because each commit was tiny.
2. Commits were tiny because we wanted them to be atomic—only one idea. For example, if I saw a spelling error in a comment, it would be its own commit. If I renamed a function, the rename refactor would be its own commit.
3. Most PRs were merged within hours of being opened. Many even sooner.
4. This is true even though we required 2 reviewers per PR.
5. It only took 10-20 minutes to review a PR
6. If PRs were big, we’d do a “Live review” over zoom to go back and forth quickly
7. Single Jira tickets that required a lot of code were PR’d in parts.
8. Almost every review comment was pointing out a blocking defect (or possible ones), not nitpicks.
9. If the code changed the UI, we’d attach before and after screenshots.

These practices helped us, but the important part is our team mindset that PRs were constructed to be easy to review.

The Liskov Substitution Principle is an Object-Oriented class design guideline that says that a sub-class should be substitutable for a super-class and that clients to the super-class should not be impacted.

You achieve this by specifying a contract for each public method of a class.

First, you specify a pre-condition/requirement.

If the caller meets the requirements, then the method makes a promise of a post-condition and result.

A sub-class is substitutable if it makes the same promises under the same requirements. It is also substitutable if it can make the same promise with fewer requirements. And, finally, it’s still substitutable if it makes more promises.

So, sub-classes can require less and promise more than the specification of their super-classes. But, they can neither require more nor promise less.

Some OO languages, like Eiffel, have ways of encoding the contract, but in Swift and many other languages, this is something usually stated in documentation.

But, substitution is not just an OO principle, or at least, I don’t only apply it to super/sub class relationships. I think it should be applied to versioning of any public library of any kind of code (OO, functional, whatever). To do this, think of vNext as a subclass of vCurrent.

So, vNext can require less and promise more. It can’t:

1. Add new required parameters to a method
2. Add exceptions to methods that didn’t have them before
3. Change the name of a method
4. Change the return type unless the new type is substitutable
5. Change parameter types unless the old type is substitutable
6. Add new required methods to a prototype

Unfortunately, many languages would think of some acceptable changes as a compile-time breaking change. For example, in Swift if a method returned T? and you changed it to return T, then callers that used guards would not compile. Strictly speaking, T is always substitutable for T?, but you should not do this change.

This is not how many library authors think, Instead, I think we’ve been corrupted by semantic versioning and the idea of acceptable breaking changes. Under substitutable versioning, there is no such thing as a breaking change.

Under semantic versioning (major.minor.patch), most library providers only think of patch version increases as being substitutable and for sure major version increases are not. I would say in practice, minor version increases are sometimes breaking.

In a fully substitutable versioning system, this would never be the case. vNext would always be substitutable for vCurrent. This means that:

1. Old classes and methods could be marked as deprecated, but are never removed.
2. Things that would be changed in major versions are done in new namespaces or with new class names.
3. To plan for this, perhaps the original namespace would use a versioning scheme.
4. Any client that compiled and worked with an old version would compile and work with a new version.

To be clear, if clients write to implementations and not specifications, they might break with future versions, so documentation needs to clearly explain what is required and promised. The actual behavior should not be confused with the contract.

A common example of this is relying on buggy behavior. If I call a method and it has some bug, I might write code to work-around that bug. If a future version fixes the bug and my software breaks because of my work-around, that’s still considered a substitutable change as the bug was not a promised behavior.

In a talk on clojure specs, Rich Hickey called this concept accretion and railed against breaking change. I know that semantic versioning is too entrenched right now to change, but something like what Rich is describing would do a lot to relieve dependency hell.

I started a podcast about a week ago and the first episode was an exercise that helped me overcome writer’s block. In the episode I said that I don’t get “coder’s block”.

This is more or less true, but I want to elaborate. I don’t mean that I can instantly solve any bug or program anything I want at will. I mean that I can make progress and do something.

When I have a problem I need to solve and literally have no idea what to do next, here are a few things that help.

1. Write down everything you know about the problem
   1. Assumptions
   2. Goals
   3. Constraints
2. Share this document with colleagues or talk to them about it.
   1. Are the assumptions and goals correct?
   2. Can a constraint can be loosened?
3. Do experiments to learn more and update your document
   1. Automated tests and scripts that help reproduce the issue
   2. User tests or analytics
   3. Diagnostic logging
4. Think bigger: Is there a fundamental problem that, if solved, makes this problem go away
5. Think smaller: Can you solve a subset of the problem

And, sometimes it’s right to put a hard problem on the back burner and come back to it later.