Contract

A good name indicates a contract with other parts of the surrounding abstraction. A variable, by its name, may indicate how it will be used or what type of value it contains and what general expectations we should have about its behavior. It's not usually thought about, but when we name something, we are, in fact, setting up a series of implicit expectations or contracts that will define how people understand and use that thing. Here are some examples of the hidden contracts that exist in JavaScript:

  • A variable prefixed with is, for example, isUser, is expected to be a Boolean type (either true or false).
  • A variable in all-caps is expected to be a constant (only set once and immutable), for example, DEFAULT_USER_EXPIRY.
  • Variables named plurally (for example, elements) are expected to contain one or more items in a set-like object (for example, an array), whereas singularly named variables (for example, element) are only expected to contain one item (not in a set).
  • Functions with names beginning with getfind, or select are usually expected to return something to you. Functions beginning with processbuild, or run are more ambiguous and may not do so.
  • Property or method names beginning with an underscore, such as _processConfig, are usually intended to be internal to an implementation or pseudo-private. They are not intended to be called publicly.

Whether we like it or not, all names carry with them the baggage of unavoidable expectations regarding their values and behaviors. It's important to be aware of these conventions so that we do not accidentally break the contracts that other programmers rely on. Every convention will have an exception where it doesn't apply, of course, but nonetheless, we should try to abide by them where possible.

Unfortunately, there isn't a canonical list where all of these contracts have been defined. They are usually quite subjective and will depend on the code base. Nonetheless, where we do encounter such conventions, we should follow them. As we mentioned in Chapter 2, The Tenets of Clean Code, ensuring familiarity is a great way to increase the maintainability of our code. And there is no better way to ensure familiarity than to adopt conventions that other programmers have come to adopt. 

Many of these implied contracts are related to types, and JavaScript, as you may be aware, is dynamically typed. This means the types of values will be determined at runtime, and the type contained by any variable may be liable to change:

var something;
something = 1; // a number
something = true; // a boolean
something = []; // an array
something = {}; // an object

The fact that a variable can refer to many different types means that the contracts and conventions implied by the names we adopt are even more important. There is no static type checker to help us. We are left alone at the chaotic whim of ourselves and other programmers. 

Later in this chapter, we'll discuss Hungarian notation, a type of naming that is useful in dynamically typed languages. Also, it's useful to know that there are various static type checking and type annotating tools available for JavaScript if you find dealing with its dynamism painful. These will be covered in Chapter 15Tools for Cleaner Code.

Contracts are not only important because of JavaScript's dynamically typed nature. They are fundamentally useful in giving us confidence in how certain values behave and what we can expect from them throughout the runtime of our program. Imagine if there was an API with a method called getCurrentValue() that didn't always return the current value. That would break its implied contract. Seeing names through the lens of contracts is quite a mind-warper. Soon, you will begin to see contracts everywhere – contracts between variables, between interfaces, and at the integration level between entire architectures and systems.

Now that we've discussed the three characteristics of a good name (purpose, concept, contract), we can begin to explore some anti-patterns, that is, ways of naming things that we should try to avoid.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.217.194.39