DEV Community

Tamás Szelei
Tamás Szelei

Posted on

How do I keep track of the vocabulary of my code?

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)

Collapse
 
ben profile image
Ben Halpern

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.

Collapse
 
tamas profile image
Tamás Szelei

Great advice. I especially like the suggestion for creating rules for naming things. Thanks!

Collapse
 
brandonskerritt profile image
Autumn

I put them into the readme on GitHub personally.