Naming
Is it a bird? Is it a plane? No! It's a... var_1?!
As famously quipped by Phil Karlton, 'There are only two hard things in Computer Science: cache invalidation and naming things'.
Naming can indeed be a subject of much debate due to its subjective nature and room for interpretation. However, while it takes time to choose meaningful names, the clarity it brings makes it a worthwhile endeavour.
Here are some guidelines to help you achieve meaningful names:
- Prioritise clarity and avoid ambiguity. Names should be descriptive and explicit.
- Maintain consistency. Strive to follow established conventions.
- Use pronounceable and searchable words. Programming is a collaborative effort, and others may need to discuss or locate your code.
- Use 'explanatory variables', separating complex statements into smaller, named pieces of code - improving comprehension.
- Avoid redundant context
- Refrain from using
Base
orAbstract
i.e. useStudent
instead ofAbstractStudent
. - Include units in names, such as
delaySeconds
, unless the type already implies it - such asdelay
for a datetime object, rather thandelayDatetime
.
- Refrain from using
- A long, descriptive name is better than a name that is short and ambigious.
- Long names can impact horizontal scrolling and make it harder to analyse associate code at a glance. This can however hint that code design can be improved.
- Avoid abbreviations and types.
- Follow the Single Truth Rule, using expressive naming "The compiler should use the same variable to represent the same single true meaning that the human reader understand" where a comment may have been used as mitigation for poor naming. If a comment says what the code could say, change the code.
- If you find yourself creating
utils
orhelpers
, reconsider their placement. Difficulty in naming might signal a need for code restructuring.
Favour 'from' over 'to'
When converting or translating values, using _to_
within function names is common.
However, this tends to separate naming from usage, fragmenting the flow for the reader.
Alternatively, using _from_
keeps related names closer: with the output described closest to assignment, and with the input described closest to the argument.
This aligns closely with the functional programming idiom of naming the function after the result it produces.
References
- Do's and Don'ts of Commenting
- Meaningful Names, Chapter 2 - Clean Code, Tim Ottinger
- Meaningful Names Revisited, Tim Ottinger
- Rules for Commenting Code, Ruthlessly Helpful, Stephen Ritchie
- Self-documenting Code
- Small Naming Tip: Use "from" Instead of "to" in Function and Variable Names, Lesley Lai