What is the Overriding Principle on Naming Conventions in PEP 8?

Question

In the PEP 8 Style Guide for Python Code, the first rule listed under Naming Conventions is the Overriding Principle.

Overriding Principle

Names that are visible to the user as public parts of the API should follow conventions that reflect usage rather than implementation.

The PEP guidelines don't give any additional details or examples, which has left me unsure of what this rule actually means.

What is the Overriding Principle in PEP 8? When would this rule apply?

Answer 1

I found this confusing too, However, I have always found that it is better to have names reflect the elements of the application domain (usage) as opposed to what work the machine is doing (implementation). Unless the domain is the machine itself then they are the same. I think this is what it is referring to.

It is easy to slip into the habit of naming things by the current implementation you are working on, because you are thinking how do I do X while you are naming things. However, when one goes to read code (especially for the first time) you are trying to understand it in the context of the system to which it belongs. So you do a service to those reading the code by naming things according to the domain.

This also has implications for refactoring. If the naming of things was more shaded to implementation you will find yourself changing more names during a refactor. Not doing so reinforces the domain.

Finally, there is a natural organization to elements in the real world. If software constructs are named according to their real world counterparts, then that organization may lend itself to the organization of the software constructs. This also makes for an easier read and potentially better software.