Be Consistent — Names, Indentation and Style
Shelfwise has get_order, fetch_customer and retrieve_book. A new developer asks: do these three words mean three different things? Does fetch call the network while get reads a cache? They don't, but the reader cannot know that without opening all three. Inconsistency makes readers study code they should be able to predict.
The rule
Same idea, same word, same shape — everywhere.
Consistency works on three levels.
Words. Choose one verb per idea and stick to it. If lookups are get_, then every lookup is get_. If a customer is a customer in one file, it is not a client or user in the next.
Shapes. Similar things should be built the same way. If every service class takes its dependencies in the constructor, a new one should too. If errors are raised as exceptions, a new function should not suddenly return -1.
Formatting. Indentation, spacing, line length and quote style. In Python, indentation is not even optional decoration: it decides which block a line belongs to.
for order in unpaid_orders:
send_reminder(order)
log("reminders sent") # outside the loop, runs onceMove that last line four spaces to the right and it runs once per order. Most languages ignore indentation, but readers never do.
A style guide (such as PEP 8 for Python) settles the questions, and an automatic formatter applies the answers so nobody argues about spaces in code review. Reviews can then focus on behaviour. A linter goes one step further and flags inconsistencies a formatter cannot fix, such as unused variables or names that break the agreed convention.
The shortcut
When you are unsure how to write something, look outward in rings: follow the file, then the project, then the language's guide. Your personal taste comes last.
Look at the file
The module already has
get_order(order_id)andget_customer(customer_id).
The trap is the "just this once" exception. One fetch_book among forty get_ functions costs every future reader a moment of doubt.
Drills
Answer fast — trust the rule.
Shelfwise has get_order and get_customer. What should the new book lookup be called?
What is the main benefit of an automatic formatter on a team?
In Python, why does indentation matter more than in Java?
You join a team whose style differs from your favourite. What do you do in your first change?
Remember
- Same idea, same word, same shape — everywhere.
- Follow the file, then the project, then the language guide; your taste comes last.
- Trap: the "just this once" exception that makes readers doubt every name.