Home Api Shame: non-Descriptive Property Names

Api Shame: non-Descriptive Property Names

This is an Article that originally appeared on “don’t code today”:
I had a lot of fun writing about the Boolean trap issue. I also have more similar API-related discussions in the pipeline. Rather than writing a long-ish essay again, I decide to put out more bite-size chunks. Here is the first.
Careful when choosing the name of an object property!
Let’s say you create a date picker component, something like depicted in the following

To set the range of the year where the user is allowed to choose a certain date, here is a bad examples of the property names:

picker.yearFrom = 1900;
picker.yearTo = 2100;

It’s quite “conversational” to decide the names like yearFrom and yearTo. A much better choice would be like this:

picker.minimumYear = 1900;
picker.maximumYear = 2100;

You could use other idioms, like start and end, if you like. The philosophy is the same, when you define a property, try to say it loud in a normal English sentence.
Here is another example. Say you want to introduce yourself:

“Hi. Call me Adam.”

Does that mean you are going to write code like this?

person.callMe = 'Adam';

Obviously not. Imagine your introduction has been changed to:

“Hi. My name is Adam.”

which is analog to the following:

person.name = 'Adam';

as if you say it (loud):

The name of the person is Adam.

Let’s for the moment assume that this introduction happens in an airport, as you exchange greetings with fellow passengers in the waiting room. The conversation continues:

“My flight is from SFO to JFK.”

Let’s write the code for that. Maybe these lines?

flight.from = 'SFO';
flight.to = 'JFK';

Again, it’s very conversational. Technically no grammar is violated is your original sentence, though imagine if it would have been rewritten as:

flight.departure = 'SFO';
flight.destination = 'JFK';

Less ambiguous? I bet!
In many cases, it’s impossible to choose one-word property name. In fact, it’s better to avoid it if that may cause some confusion.
If you have a scrolling list, where the user can swipe his finger horizontally or vertically, one way to specify it is:

X.scroll = 'horizontal';
Y.scroll = 'vertical';

Still considering the original observation that:

the code is usually written once but read many times.

those two lines lead to an ambiguity because scroll as a word can mean a lot. At least, it’s a verb and also a noun (though the latter often connects to the magical world). What you really want people to understand is perhaps:

X.scrollDirection = 'horizontal';
Y.scrollDirection = 'vertical';

Say it loud and it makes sense:

The scroll direction of X is horizontal.

I hope you get the idea. See you in the next installment!
Source Ariya Ofilabs

About ReadWrite’s Editorial Process

The ReadWrite Editorial policy involves closely monitoring the tech industry for major developments, new product launches, AI breakthroughs, video game releases and other newsworthy events. Editors assign relevant stories to staff writers or freelance contributors with expertise in each particular topic area. Before publication, articles go through a rigorous round of editing for accuracy, clarity, and to ensure adherence to ReadWrite's style guidelines.

Get the biggest tech headlines of the day delivered to your inbox

    By signing up, you agree to our Terms and Privacy Policy. Unsubscribe anytime.

    Tech News

    Explore the latest in tech with our Tech News. We cut through the noise for concise, relevant updates, keeping you informed about the rapidly evolving tech landscape with curated content that separates signal from noise.

    In-Depth Tech Stories

    Explore tech impact in In-Depth Stories. Narrative data journalism offers comprehensive analyses, revealing stories behind data. Understand industry trends for a deeper perspective on tech's intricate relationships with society.

    Expert Reviews

    Empower decisions with Expert Reviews, merging industry expertise and insightful analysis. Delve into tech intricacies, get the best deals, and stay ahead with our trustworthy guide to navigating the ever-changing tech market.