Marcus Wood

AboutProductsBlog

Does your Code Pass the Jeopardy Test?

#documentation#javascript#style

We've all heard the quote, "There are only two hard things in Computer Science: cache invalidation and naming things." While naming something isn't inherently difficult, giving a name that describes the lasting intent is. I think that's ultimately what makes it so hard when you're coding because slapping a variable name on something while you're in the zone is inconsequential. You say, "I'll always remember what that means down the line" and then two months later you go back and have no idea why the variable name is bananaTrees.

This is where the Jeopardy test comes into play. Every time you declare a boolean variable phrase it in a question. Instead of an enabled flag add isEnabled. The reason is because it's the first thing that someone (or your future self) is going to ask when they read it is, "What is enabled?"

Prepend every boolean variable or property with "is"

A Brief History on Jeopardy

If you're not familiar, Jeopardy is an American game show where contestants are quizzed on various topics and they have to answer in a form of a question. This game came off the heels of the 50s quiz show rigging scandals causing ratings to plummet. So how do you keep people from rigging the shows? By giving the answers first and having the contestants guess the questions! The format of Jeopardy has changed from its early days, but answering in a phrase of a question is still around.

Take out the Guesswork

That's what so beautiful and simple about prepending any boolean variable name with intent. You're not trying to guess the answer of what the thing does because you're giving your future self the answer. This can be applied to any language, but is most important in dynamically typed languages like JavaScript since there are no type annotations to help you along. For example, you'll often see the flag enabled declared.

// Doesn't tell us much
const enabled = false
// A little better, now we know the intent and that that the variable
// is a boolean
const isEnabled = false
// Perfect! From the name we can infer the type of the variable
// and what it's describing
const isUserEnabled = false

Most of the time you can assume that enabled or disabled will be booleans since it's fairly standard throughout languages and APIs. But let's say we're defining an email document that will be stored in a database. An example document might look like this:

const emailDocument = {
subject: 'Welcome!',
id: '123456',
body: 'Hey there!',
user: '435',
admin: true,
read: false,
enabled: true,
sent: '2020-02-03'
}

When you have the data attached, it's not too hard to determine what each property name is. However, let's take those off:

const emailDocument = {
subject,
id,
body,
user,
admin,
read,
enabled,
sent
}

Is "sent" the time it was sent or if it was sent? Is "user" the associated user or if it is intended for a user? What is "admin"? If you don't have the data available, it's impossible to determine what these properties mean. This introduces friction into what you're coding and can create bugs. Let's clean it up:

const emailDocument = {
subject: 'Welcome!',
id: '123456',
body: 'Hey there!',
fromUser: '435',
isAdministrativeEmail: true,
isRead: false,
isEnabled: true,
sentOn: '2020-02-03'
}

Now we don't need to know the data or even consult the docs (if there are any) to infer what a property means. It is hard to name things, especially when working on large teams or creating an API. This is one small tip that I've seen pay off big in the long run and hope it helps.

Want more content like this?

Sign up to receive my newsletter, where I feature early access to new products, exciting content, and more!

Marcus Wood is a JavaScript software engineer that focuses on building products using Typescript, React, and GraphQL. He has built and delivered solutions for some of the largest companies in the world.

Contact

Newsletter