Representation principle: naming of programming variables

A variable name MUST represent the TYPE, TASK, and ORIGIN of its value independently. This principle requires the naming of variables to be comprehensive but not detailed.

Variable and its value

class Post
  hasAuthor
  # ✔ type: boolean, due to `has` keyword
  # ✔ task: finds if there is an author of the Post
  # ✔ origin: Post class itself

The idea here is a developer reading your code could understand what exactly your variable does without a need to analyze its value or any other parts of the application.

Variables don’t need to disclose their origin if the origin is the context itself. As the hasAuthor variable doesn’t have any context disclosure in its name, we can freely assume that it refers to its class Post as its origin.

class Post 
  setName
  # ✔ type: function
  # ✔ task: editing or creating the name of Post
  # ✔ origin: Post class
setAuthorName
  # ✔ type: function
  # ✔ task: editing or creating the name of author
  # ✔ origin: Post class, author variable
setAuthor
  # ✔ type: object (Hashmap), as it stands for a model
  # ✔ task: set all setups of author variable
  # ✔ origin: Post, as it is not stated inside the variable name.

For the sake of simplicity let’s look at some deeper examples. In React we use useState, useEffect hooks. The origin of those variables is React’s hooks itself. We can guess it from theusepreposition. The principle is easier to comprehend in object-oriented code, however, it is also pretty compatible with functional programming methods.

There are numerous use cases of variable names which are bad practices due to this very principle and other common readability best practices. Let’s reflect:

User
  setValue
  # ✔ type: function
  # × task: is not comprehensive as we don't know which value is being set. 
  # ✔ origin: User

As we can’t understand what exactly this function does without looking at the value or the other parts of the code, it goes against the principle.

There are some cases where variable names are more detailed than expected. For example, setUserName in must be setName as we are in the User context, and it shouldn’t give excessive information about the task. Or getUserInfoFromDB is also breaking the rule due to the unnecessary procedural details. getInfo sounds better.

Polysemantic names like check , handle , look , find , etc. should also be avoided in many cases. handle keyword may only be used as an event handler in React. That means handle is a result of something else. handleClick suggests “Do this after click happens”. Using it in other cases creates ambiguity.

addDataToTable -> which data? defaultKinds -> Kinds of what? myItems -> Nothing is yours, be more specific. Questions here are important.

If anyone feels the necessity to see other code blocks to understand your variable name, it is most probably by virtue of the wrong naming.

We should state the wrapping context and dependencies as exceptions. setName(value) is eligible with our standard.