I often find code I've written that uses different vocabulary for the same things. For example, we have a term variant (referring to a variant of our product), but sometimes it's written as variation. It's an absent-minded, honest mistake, but once it's in and used in different interacting codebases, it's really hard to get rid of.
Another common source of confusion is using the same word to mean different things. If I sat down I bet I could find at least three completely different usages of the term build (just from the top of my head, it could mean: a configuration, a build artifact, a ci job, a particular run of a ci job - hey, that's four already!).
So my question is: how do I improve this? I'd like to be mindful of my word choices because I feel like it has a huge impact on the readability and maintainability of the code (not only positively: when it's less than ideal, those metrics suffer, too). At the same time, working on 6-7 interacting codebases, it feels impossible to keep all the wording the same. Any advice?
Top comments (3)
I'd bet that establishing good documentation habits could go a long way here. Just writing down some project guidelines/constraints. Loose rules for the type of ways you name things? If you have a theme of how things are generally named than the right consistency might come to you.
One more thing: Good tests and regular refactoring. If you do happen to get in a situation where you'd like to make areas of the code more consistent, being confident that you can make sweeping changes without breaking things is a good place to be.
Great advice. I especially like the suggestion for creating rules for naming things. Thanks!
I put them into the readme on GitHub personally.