# Here's a picture of my microwave:

# Hah! No, that's silly. Here's my microwave.

# Here's some code.

<LayoutContentPanel id="lcpReport" heightSizeMode={eccw.PanelSizeMode.fill}>
  <div style={{ height: "430px" }}>
    {(this.Data.AppliedCard) ?
      <div id={HTMLElements.AppliedReport}>{this.__loadReport(true, false)}</div> :
      <ZeroStateControl className="_full-height" message={Resources.NoCardApplied}
        ref={(zsc) => { zsc.show(); }} />}
  </div>
</LayoutContentPanel>

# The __loadReport(true, false) is the same as the blank buttons on the microwave

In both cases, you ask: what does this do?

On the microwave, if I push one of the white oval buttons, what will that do?

In the code, when I load the report, and say true, what will that do?

# A programming environment is a user interface for understanding a program

See Read The Vocabulary from Bret Victor’s essay on Learnable Programming.

It’s a great essay, a sort of a mix of The Design of Everyday Things and Clean Code and its ilk. (You have read both, right? Right?)

# Not just nice-to-have. This causes actual bugs.

I work at a company that makes software for electronic health records. One thing it does is let doctors order medications for patients. We do things like check for duplicates, and so on.

Messing up those checks is not just a computer problem, it could possibly affect a patient's health. So we need to show messages correctly.

I once fixed a bug that came down to a line of code like this:

$$(this).showMessage(ClientResources.MedExactDuplicateMessage, ClientResources.MedDuplicateCaption, MessageBoxButtons.OK, MessageBoxIcon.Error, undefined, $$fcb(this, this.__undoDuplicateMedication, index, column), null, undefined, undefined, undefined, undefined, String.format(ClientResources.MedExactDuplicatePrimaryMessage, exactDuplicate + 1));

The problem came down to the original programmer missing a "true" in the 15th parameter above. Not a joke!

# Which is easier to read? A better user interface?

Forget about bikeshedding about whether boolean parameters are a code smell. Which is better?

this.__loadReport(true, false)

or

this.__loadReport({showExtraStuff: true, showDefaultThing: false})

# Code is a user interface to the reader

Make it a good user interface! Think about usability principles and your users -- fellow programmers reading the code.

# But good UI isn't always verbose or explicit

The above examples seem to favor naming and labeling everything, of being verbose. Very often, that's good, but keep in mind that not everything needs to be that way. For example, here's another user interface:

But think about what the user does with the above shifters and brake, the context in which they do it, and their needs when doing that -- compared with what a user -- a programmer -- does when reading code, and their needs when doing that.