3.3. Summary¶
Choosing names has nothing to do with algorithms or computer science, and yet it’s a vital part of writing readable code. Ultimately, the names you use in your code are up to you, but be aware of the many guidelines that exist. The PEP 8 document recommends several naming conventions, such as lowercase names for modules and PascalCase names for classes. Names shouldn’t be too short or too long. But it’s often better to err on the side of too descriptive instead of not detailed enough.
A name should be concise but descriptive. A name that is easy to find using a CTRL-F search feature is the sign of a distinct and descriptive vari- able. Think about how searchable your name is to determine whether you’re using a too generic name. Also, consider whether a programmer who doesn’t speak fluent English would understand the name: avoid using jokes, puns, and cultural references in your names; instead, choose names that are polite, direct, and humorless.
Although many of the suggestions in this chapter are simply guidelines, you should always avoid names Python’s standard library already uses, such as all , any , date , email , file , format , hash , id , input , list , min , max , object , open , random , set , str , sum , test , and type . Using these names could cause subtle bugs in your code.
The computer doesn’t care whether your names are descriptive or vague. Names make code easier to read by humans, not easier to run by computers. If your code is readable, it’s easy to understand. If it’s easy to understand, it’s easy to change. And if it’s easy to change, it’s easier to fix bugs or add new features. Using understandable names is a foundational step to producing quality software.