E.g., the function and parameter are named poorly here, and so comments need to do all the heavy lifting:

// function to convert temperature from Fahrenheit to Celsius scale
// temp is the temperature in Fahrenheit
double unitConverter(double temp)

Contrast it with this:

double fahrenheitToCelsius(double tempFahrenheit)

No need for a comment here!

Examples:

• In a nested loop, using j for outer and i for inner loop index is confusing!

  for (let j = 0; j < arr.length; j++) {
    for (let i = 0; i < arr[j].length; i++) {

• tmp shouldn’t be used to store objects that are not temporary
• retVal shouldn’t be used for objects not returned from a function

All variables are temporary in some sense. Calling one tmp is inviting carelessness.

# generic name
if (right < left) {
  tmp   = right
  right = left
  left  = tmp
}

# more descriptive
if (right < left) {
  old_right = right
  right     = left
  left      = old_right
}

For example, these names are inconsistent since the reader can’t safely assume that the name size means the same thing throughout the program.

// context-1: `size` stands for number of memory bytes
{
  size = sizeof(x);
}

// context-2: `size` stands for number of elements
{
  size = strlen(a);
}

// context-1:
{
  size = sizeof(x);
}

// context-2:
{
  length = strlen(a);
}

You can typically find a middle ground between too short and too long names.

# not ideal - too imprecise
d

# okay - can use more precision
days

# good - middle ground
days_since_last_accident

# not ideal - unnecessarily precise
days_since_last_accident_floor_4_lab_23

...

E.g., here is a GUI text editor class method to get position of a character:

std::tuple<int, int> getCharPosition(int x, int y)

How I interpret: “x and y refer to pixel positions for a character.”

In reality: “x and y refer to line of text and character position in that line.”

You can avoid such misinterpretation with better names:

std::tuple<int, int> getCharPosition(int lineIndex, int charIndex)

E.g. nn and nnn are easy to be confused and such confusion can lead to painful bugs.

// bad
let n   = x;
let nn  = x ** 2;
let nnn = x ** 3;

// good
let n       = x;
let nSquare = x ** 2;
let nCube   = x ** 3;

E.g., this function uses a and f parameters to represent an array and a function.

# bad
arrayMap <- function(a, f) {
  ...
}

# good
arrayMap <- function(arr, fun) {
  ...
}

If needed, it wouldn’t be easy either to search for and/or to rename these parameters in the codebase because searching for a or f would flag all as and fs (api, file, etc.).

Instead, if more descriptive identifiers are used, both search and replace operations will be straightforward. In general, searchability of a name indexes how generic it is.

For example, C++ convention is to use PascalCase for class names and lowerCamel case for variables.

// non-conventional
class playerEntity
{
  public:
    std::string HairColor;
};

// conventional
class PlayerEntity
{
  public:
    std::string hairColor;
};

In general, use positive terms for Booleans since they are easier to process.

# double negation - difficult
is_firewall_disabled <- FALSE

# better
is_firewall_enabled <- TRUE

E.g., consider variables that store data in different data structures or cloud services:

# bad
bonuses_pd  # pandas DataFrame
bonuses_pl  # polars DataFrame

aws_s3_url  # AWS bucket
gcp_url     # GCP bucket

# good
bonuses    # data structure independent

bucket_url # cloud service independent

For example, let’s say your class has the $getMeans() method.

• In its initial implementation, it used to return precomputed mean values.
• In its current implementation, it computes the mean values on the fly.

Therefore, it is misleading to continue to call it a getter method, and it should be renamed to (e.g.) $computeMeans().

If you are writing a function to generate a time-stamp, discussing the following function verbally would be challenging.

# generate year month date hour minute second
genymdhms()

This is a much better (and pronounceable) alternative:

generateTimeStamp()

Additionally, avoid naming separate entities with homonyms.

Discussing entities named waste and waist is inevitably going to lead to confusion.

E.g., two similar methods here have different names across R6 classes:

CreditCardAccount$new()$retrieve_expenditure()
DebitCardAccount$new()$fetch_expenditure()

Both of these methods should either be named $retrieve_expenditure() or $fetch_expenditure().

• Don’t use slang. You can’t assume current or future developers to be familiar with them. E.g. exit() is better than hit_the_road().

• Avoid unintended meanings. Do your due diligence to check dictionaries (especially Urban dictionary!) if the word has unintended meaning. E.g. cumulative_sum() is a better function name than cumsum().

• Avoid imprecise opposites, since they can be confusing. E.g. parameter combination begin/last is worse than either begin/end or first/last.

• Don’t use hard-to-distinguish character pairs in names (e.g., l and I, O and 0, etc.). With certain fonts, it can be hard to distinguish firstl from firstI.

• Don’t misspell to save a few characters. Remembering spelling is difficult, and remembering correct misspelling even more so. E.g. don’t use hilite instead of highlight. The benefit is not worth the cost here.

• Don’t use commonly misspelled words in English. Using such names for variables can, at minimum, slow you down, or, at worst, increase the possibility of making an error. E.g. is it accumulate, accummulate, acumulate, or acummulate?!

• Don’t use numeric suffixes in names to specify levels. E.g. variable names level1, level2, level3 are not as informative as beginner, intermediate, advanced.

• Don’t allow multiple English standards. E.g. using both American and British English standards would have you constantly guessing if the variable is named (e.g.) centre or center. Adopt one standard and stick to it.

• Don’t use similar names for entities with different meanings. E.g. patientRecs and patientReps are easily confused because they are so similar. There should be at least two-letter difference: patientRecords and patientReports.

Statistical distributions can be characterized by centrality measures, and R has functions with names that wouldn’t surprise you, except one:

x <- c(1, 2, 3, 4)
mean(x)   # expected output
median(x) # expected output
mode(x)   # unexpected output!

The mode() function actually returns the storage mode of an R object!

This function could have been named (e.g.) storageMode(), which is more precise and doesn’t break domain-specific expectations.

size is a bit better but still leaves room for misunderstanding:

“Does it mean length or memory bytes?”

Here is an alternative parameter name:

template<
    class T,
    std::size_t numberOfElements
> struct array;

numberOfElements is more precise and unmistakable.

A user now believes that both spelling standards for function names and parameters are supported. And, since they prefer American spellings, they do this:

guide_colorbar(ticks.color = "black")

That won’t work! Both functions support only the British spelling of parameters:

guide_colourbar(ticks.colour = "black")
guide_colorbar(ticks.colour = "black")

This is inconsistent and violates the user’s mental model about naming schema.

But filter is an ambiguous word. It could mean either of these:

• to pick out elements that pass a condition (what remains after filtering)
• to pick out elements that need to be removed (what is filtered out)

If you’ve never used this function before, could you predict if it returns 1 or -1?

It returns 1, so the intent is to pick out the elements that pass the condition.
In this case, keep() would be a better name.

Had the intent been to find elements to remove, discard() would be a better name.

Consider a function to extract a table of regression estimates for a statistical model. For convenience, it also allows sorting the table by estimate.

`???` <- function(model, sort = "asc") {
  # code to extract estimates from model
  ...
  # code to sort table
  ...
}

extract_estimates <- function(model) {
  # code to extract estimates from model
  ...
}

sort_estimates <- function(table, sort = "asc") {
  # code to sort table
  ...
}

Consider a function that converts Markdown or HTML documents to PDF.

convert_to_pdf <- function(file, is_markdown = FALSE) {
  if (is_markdown) {
    # code to convert Markdown to PDF
    ...
  }

  if (!is_markdown) {
    # code to convert HTML to PDF
    ...
  }
}

convert_md_to_pdf <- function(file) {
  # code to convert Markdown to PDF
  ...
}

convert_html_to_pdf <- function(file) {
  # code to convert HTML to PDF
  ...
}

• Intent-revealing names make the code easier to read.

• Trying to find good names forces you to detach from the problem-solving mindset and to focus on the bigger picture that motivates this change. This is critical for thoughtful software design.

• Searching for precise names requires clarity, and seeking such clarity improves your own understanding of the code.

• Naming precisely and consistently reduces ambiguities and misunderstandings, which in turn reduces the possibility of bugs.

• Good names reduce the need for documentation.

• Consistent naming reduces cognitive overload for the developers and makes the code more maintainable.