DEV Community

Hudson Burgess
Hudson Burgess

Posted on

How much should you refactor names when domain terminology changes?

This is hard to explain in the abstract, so here's a hypothetical scenario:

You're building an app to manage inventory for a store that sells computer monitors. One day, the store decides that in the future monitors will be called "displays." Your managers promptly commit to this terminology change in conversations with you, and the marketing team ensures that all of their content reflects the change too. To the company, this change in terminology is important.

As a developer and a software craftsman, should you:

  • refactor all occurrences of monitor in your code to display (in class names, variable names, folder structure, etc.) to keep the terminology consistent?
  • leave the names alone because only the devs will see them, and the mismatch in terms will probably not cause any confusion?
  • something else?

How much should you refactor names when domain terminology changes?

Top comments (13)

Collapse
 
kspeakman profile image
Kasey Speakman

I tend to take naming pretty seriously. I'm as bad at naming things as the next person. But when I do finally stumble upon the right name for something, I go back and make it consistent in the code.

The main reason I do this is because naming is a real problem in our legacy code base. More than once I have completely misinterpreted some old code because of the names that were used. For example, it is pretty common in our code base for an array of something to be named as a singular -- the variable is named customer but it is actually a list. Or vice versa -- customers is actually a single Customer. Or data types are named for the effect they are intended to have instead of what they are -- a type containing customer data is called Email because the data is intended to be used for emailing. So now it is a personal goal of mine to fix bad naming whenever I see it, and suggest alternatives to poor naming in code reviews... because it is a problem we definitely have.

Maybe not directly addressing your question... for actual domain code, I would be quite inclined to rename things. But as with everything, you have to weigh the cost. As @alainvanhout said, if naming changes are very frequent, it makes little sense to continually go back and rename. I would probably make a story to collect the name changes and perform a batch of them at once.

Collapse
 
dmfay profile image
Dian Fay

It's good to keep nomenclature consistent since if someone joins your team they won't have the historical knowledge that a "monitor" is what everyone else calls "display" and is only labeled "monitor" in legacy code, but it's also pretty low-priority as refactors go. Good to do it eventually, no need to jump on it immediately.

Collapse
 
hudsonburgess7 profile image
Hudson Burgess

if someone joins your team they won't have the historical knowledge

One of my top reasons for doing this kind of refactor. I'm essentially the only frontend dev at my company, so it's a non-issue at the moment :P but I don't want to confuse future devs either

Collapse
 
alainvanhout profile image
Alain Van Hout

If it's a single (naming) change, then after a while it may make sense to move to that terminology. Though if changing names/terminology happens frequently, then it makes little sense to keep changing your code to match it. A glossary would then better serve a new developer.

Collapse
 
hudsonburgess7 profile image
Hudson Burgess

A glossary would then better serve a new developer.

Hadn't considered that, great idea

Collapse
 
itsasine profile image
ItsASine (Kayla)

Ha, my project at work has this issue. 2 years in and we're still finding things called "team" instead of "group".

Even with that project clouding my opinion, I still think every project should do a renaming. Especially since in an IDE like IntelliJ, it will rename all instances of the thing. You'll have to take the time to do a solid refactor rather than a find replace to do it right, but it'll pay off so much in the long run.

I tend to stick with the stance that good code should be documentation in and of itself, and a large part of that is having clear and descriptive naming conventions. If someone wanted a new person to the team to implement a fix to how displays are sorted, the new person could spend an hour or more hunting for that code and examples how to do it without knowing they were ever called monitors.

Collapse
 
sharpdog profile image
SharpDog

If it is in a few well determined and localized places then I refactor the names. If it is a part of a major series of dependent changes, on multiple levels, multiple modules / subsystems, etc. then I leave it alone. For example, in our current system of many applications, several web sites, many middle and back end services we have an annoying misspelling which I'n not suggesting fixing because it basically touches everything. The same would happen on a domain terminology change.

And sometimes even more unfortunate naming happens. In my previous company we used the term 'category' for four completely different concepts. This led to much confusion and would severely complicate name changing.

Collapse
 
cjbrooks12 profile image
Casey Brooks

I completely agree with this, if the scope is small and well-isolated, go ahead and make the change. For parts of your code that are large-spanning or change the public API (such as query parameter names or keys in JSON responses), leave them alone until they need to be changed.

And when you're renaming stuff, make sure to be very careful and very thorough with it. Small commits changing just a few files at a time is much better than one large one (you can always squash the commits in the end before merge). IDEs can sometimes get a bit too aggressive with renaming, so don't just "replace all", step through each and every match and verify that each match you do actually want renamed.

Collapse
 
hudsonburgess7 profile image
Hudson Burgess

Definitely guilty of making enormous and aggressive "renamed X -> Y" commits. Didn't think about squashing smaller commits, even though I do that for feature branches all the time.

Collapse
 
spidergears profile image
Deepak Singh

I always like align the nomenclature in code with the daily business terminology in use. If business call it a display, code should reflect the same.

Now the problem is making this change, depending on the size of the code base and the public exposure(are there any public apis exposed that might need to be updated), this can be changed in a phased manner. Extreme care needs to be taken, since this can introduce reference errors.

Collapse
 
chiangs profile image
Stephen Chiang

This just happened to me. This product went from nameA to notEvenRemotelySimilarName.

I recommended to refactor all instances of the name, but then almost all the way compelete, we find out that we can't change the name on the API side because other production apps depended on the name and they weren't changing the product name...so we reverted and wrote a continuity comment on the naming...a few weeks later... The product was killed altogether #timeWellSpent

Collapse
 
hudsonburgess7 profile image
Hudson Burgess

Ouch...
I've run into the API problem before too

Collapse
 
fnh profile image
Fabian Holzer

Coding in the language of the domain is generally a good principle and having a Ubiquitous Language can be a very valuable property of a system, but if the language is flaky and development is kept out of the loop (which is the impression I'd get in case of your hypothetical scenario), chances are there is no buy-in from the business side into a domain driven design of your system. In that case, I would make it dependent on how grave the changes in terminology are, and how much effort is required, and how risky it is to do changes in the code, whether or not I'd refactor promptly or just make a note somewhere.