** This is a work in progress, that mostly contains lots of good links **
It’s one of the hardest things you do a programmer and also one of the most important aspects of writing code. Code is read 10x more than it’s written so when you are writing you need to be very thoughtful of the future readers, which are yourself & others. You want your code to be very clear to readers, even if you are the only reader. Readability makes or break a project There has been plenty of times that I don’t look at a piece of code for months and come back and have to re-learn what I what I was doing.
An important principle for naming is to communicate intentions.
The process of thoughtful naming also help you to identify code smells. If you are having a hard time naming a class, it may do too many things and should be possbily broken down.
Purpose & Potential
There is this idea that people live up to their names, & derive meaning/purpose from their name. You should apply this notion of naming things to objects. Naming something gives it a purpose & meaning - it essentially creates it’s “definition”. If you name an object generically, it doesn’t have clear definiion, clear boundaries. Due to this lack of focus an object can quickly end up doing more than it should which lead be bad code smell.
Is there a physical object that can help describe
When you are struggling with naming something, created wordmaps, word graphs from the name or concept that you are starting with.
Using a thesarus helps you to find similar terms that may better communicate intent &/or context
Inversely, if you enter your variable or method on the link and it’s on the list then you probably shouldn’t use the name.
- Names that reveal intent
class CommentModeratorencapsulates logic for moderating comments
find_configs(directory)returns list of configs from a directory
is_risky_command(command)returns true/false of risk of command
- Names that remove need for comments
- Be consistent
- To name things that correlate to the domain
- Accurately describe the variable or method
- Conciseness over verbosity
- Use analogies & metaphors
- Scalable patterns
- Have some fun
- One letter or Short names
- Don’t use
- Generic terms like Manager or Provider or words
class ServiceProvider ...
list = ['a', 'b', 'c']
word = "word"
file_handle = open('output.log')
- Uneeded abbreviations or prefixes/suffixes
- Including type in variable
- Misleading names
words = [1, 2, 3]
has_word(sentence) # -> but returns 'string'
- Methods or functions that describe how it works