The Naming Checklist

There are only two hard things in computer science: cache invalidation and naming things. - Phil Karlton

1. Give meaningful names

Of course, you will not name cats as dogs, But giving meaningful names goes beyond that. A well-named element is clear, concise and communicates the context of its usage

For, e.g.,

date_added is better than date created_date is better than date_added

2. Don’t eat characters

Don’t drop characters because it makes sense(to you). After all, we aren’t in the SMS era. Look at the following examples. It almost feels like playing a guessing game every time you come across these names.

  • tbl - what’s gonna kill you if you write table
  • ts - time in seconds? Timestamp?
  • sec - section or seconds?

You see the problem. Always use full definitive words when naming things.

3. Use a thesaurus

Finding a perfect word to fit the functionality can be hard. That’s when a thesaurus can come in real handy. Why not dig into the powerhouse of writers and grab some inspiration. For, e.g., time_passed says something about time and an event, but it’s not definite. Whereas elapsed_time is definite, on point, and crisp.

4. Be consistent

When you write code, it’s often used by different stakeholders. It is important to keep the interfaces and Signatures consistent in their names. If all your interfaces use get don’t introducefetch out of the blue. Pick one and stick to it.

5. Follow language guidelines

Similar to do what Romans do in Rome. Follow the casing and conventions of the language. E.g., JS uses camelCase readLines where as python uses snake_case ` read_lines `

6. Boolean

The thumb rule of boolean variables is to raise a question that poses a true or false answer. Is, has, can, or should can make booleans crisp.

For eg.,

sortable = true or is_sortable = true

hidden = true or is_hidden = false

7. Use tmp wisely

Use tmp variables only when they are temporary. For example, swapping two numbers, writing to a tmp file.

8. Naming Collections

When using lists, instead of using types like fruitsArr, use fruits. Whereas when it comes to dictionaries, provide the context of the mapping. user_to_group is better than user_dict.

9. Function names should be verbs

The sole purpose of functions is to perform some action. So ensure your name accompanies them with words. get_user(user_id) is better than userinfo(user_id).

Another thumb rule of functions is to use verbs that are closer to the action performed. compute_mean(array) is better than get_mean(array) as it signifies that the mean is computed every time, which alerts a programmers brain of complexity

10. Quantify the limits

Be more definite about the limits when it comes to Quantifying variables. For, e.g., BLOG_TOO_BIG is a vague quantifier. What quantifies big? The number of characters? Words or blocks? Whereas MAX_WORDS_PER_BLOG quantities blog too big to the number of words.

Your code should be a museum, well documented so that people can enter and exit with ease. They should at least have a template to walk around. - Bhavani Ravi