Meaningful Names for Variables and Functions
You'll learn how to write self-documenting code by choosing names that clearly reveal what your variables store and what your functions do.
Why Names Matter
Every variable and function you create tells a story. A good name answers three critical questions without forcing readers to hunt through code or comments: What does it hold? Why does it exist? How should I use it?
Think of names like labels in a well-organized workshop. A drawer labeled "phillips_head_screws" is infinitely more useful than one labeled "stuff2" or just "s". The same principle applies to code.
The Core Principle: Reveal Intention
Bad naming:
d = 86400 # seconds in a day
Good naming:
seconds_per_day = 86400
The second version eliminates the comment because the name is the explanation. When you write function1() or temp, you force every reader (including future you) to decode your intent. When you write calculate_user_discount() or active_user_session, the purpose is immediately clear.
Practical Guidelines
- Be specific, not generic: Use
customer_email_listinstead ofdataorlist1 - Avoid mental mapping: Don't make readers translate
i,j,kinto actual meanings outside simple loop counters - Use pronounceable names:
gen_ymdhmsbecomesgenerate_timestamp - Make distinctions meaningful: If you have both
get_active_account()andget_active_accounts(), the singular/plural distinction matters
The anti-pattern you just learned about—Big Ball of Mud—often starts with lazy naming that snowballs into incomprehensible chaos.
Key Takeaway: Good names eliminate the need for comments by making your code's purpose self-evident; invest time in naming because code is read far more often than written.