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
date_added is better than
created_date is better than
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 introduce
fetch 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 `
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.
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
fruits. Whereas when it comes to dictionaries, provide the context of the mapping.
user_to_group is better than
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
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