Needlessly short names

Names that are too short are usually employing either program-specific knowledge or domain-specific knowledge that may not generalize well to the audience of the code. A lone programmer may think it reasonable to write the following code:

function incId(id, f) {
for (let x = 0; x < ids.length; ++x) {
if (ids[x].id === id && f(ids[x])) {
ids[x].n++;
}
}
}

We are able to discern the fact that it is related to IDs and its purpose is to conditionally increment a specific object's n property within the ids array. Therefore, it is possible to discern what it is doing on a functional level, but its meaning and intent are difficult to grasp. The programmer has used single-letter names (f, xn) and has also employed an abbreviated function name (incId). Most of these names fail to fulfill the basic characteristics that we desire from a name: to indicate purpose, concept, and contract. We can only guess at these names' purposes and concepts by how they are being used. It would vastly help to refactor this with more meaningful names:

function incrementJobInstancesByIdIfFilter(id, filter) {
for (let i = 0; i < jobs.length; i++) {
let job = jobs[i];
if (job.id === id && filter(job)) {
job.nInstances++;
}
}
}

We now have a far clearer idea of what's going on. The arrays being iterated over contains jobs. The function's purpose is to find jobs with a specified ID and conditional on that job satisfying a specified filter. It increments the job's nInstances property by 1. Via these new names, we already have a far richer conceptual understanding of this abstraction. We now understand that jobs are items that can have any number of instances and that the number of current instances is tracked via the nInstances property. Via the lenses provided by the names, we have been able to understand the underlying problem domain more clearly. Now, we can see that names are not just decoration or needless verboseness; names are the very essence of your abstractions. 

A needlessly short name is, in many ways, just an insufficiently meaningful name. However, a name being short does not necessarily indicate a problem. The iterator variable, i, which we used in the preceding code, is perfectly fine as it is a convention that has established itself over decades. Programmers all over the world understand the conceptual and contractual implications of it: it is used only to iterate through an array and to access array elements at each stage of the iteration.

On the whole, and outside of rare exceptions such as our iteration variable, it is incredibly important to avoid the deficit in meaning that is invited by short names. They are often composed initially with haste or laziness and may even give the programmer attuned to their meaning a sense of accomplishment. After all, being able to wield obscure logic is a gift for the ego. But as we've covered, the ego is not a friend to clean code. Whenever you feel the urge to use a short name, push back on the impulse and take the time to pick a name that is richer in meaning.

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

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