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 tablets
- 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