In my talk The importance of naming, I set out six naming principles:

1. Use only one name to refer to a concept. Each concept must have one name only. If a concept has multiple names, decide on its canonical name, and stop using other names.

2. Give different concepts different names. Each name must be used for one concept only. If a name refers to multiple concepts, decide on its canonical concept, and stop using it for other concepts.

3. Rename concepts when principles are violated. I expect principles to be broken over time, as software evolves. Make renaming quick and easy.

4. Ensure names match meaning. A name is no good if it is difficult to remember what it stands for, or when it seems to fit another concept better.

5. Break up concepts that cannot be named properly. If a single concept cannot be named appropriately, it is likely that this single concept is a set of multiple concepts, in the guide of a single one. Note that breaking up a concept could require many changes, including database schema changes.

6. Be consistently correct. Consistency brings predictability, and predictability keeps cognitive overhead low.

Tips

Create a glossary. Keep maintaining that glossary.

Use deprecation mechanisms that your language or frameworks provide. Source code comments can be appropriate for that purpose.

See also

• Approaches to naming products