We've had a long living product for about 8 years now. Over time, the names of concepts and entities change. Should we put the work in to rename all the code base and database tables and columns to match these new names?
Is there a study made on this or some best practices published?
Thanks
The mismatch between internal and external names definitely smells. Like Rinzwind points out, the homophones and synonyms smell the worst.
The real question you need to answer is: What is the cost/benefit tradeoff in making the change?
The cost of not changing is a steeper learning curve for new team members and increased likelihood of future bugs. The cost of changing is the obvious time involved, a new learning curve for old-timers on the project, and the possibility of new bugs.
If you are expecting to have a relatively large number of new team members, it is more likely to make sense to make the change. If you are not expecting any turnover, the current team doesn't tend to get confused, and the team is satisfied with the status quo, then it doesn't really make sense to rename things.
If the code is expected to live for a long time and there will be new developers working on it, I would make the changes.
It can be very confusing and time consuming for a new developer to enter into a project and find the names of entities are misleading.
There is also the valid argument of...If it ain't broke, don't fix it.
With regards to your second question, I'm not aware of any published studies or best practices. With regards to the first question, I can offer some observations from personal experience with a similar long-living product where the ‘internal’ and ‘external’ names are sometimes different.
The names that I would really like to fix are the “homophones”, where one name is used both internally and externally for different things. This can be really confusing, particularly if the two things are not completely different (such that context helps disambiguate). One (abstracted) example of that in my personal experience is where internally you have something like a Foo which is a collection of multiple FooEntity; externally, only the latter is visible and is called a “Foo”. Took me a while to figure out that when the customer manual was speaking of multiple “Foo” it actually meant multiple FooEntity (in a single Foo), if that still makes any sense to you.
Secondly, I would like to fix any “synonyms” where some external name has been used internally. Like in variable names, parts of method/function names and so on. This often happens when developers implement something directly from a customer requirements description and forget to “translate” the names. Once that happens, the ‘wrong’ name also tends to spread, because other developers happen to copy/paste some of that code to use as a template for new code for example. These synonyms are not so confusing, but they can be annoying because if you are searching the code for any references to Bar you may have to keep in mind that some parts may refer to it as Qux, so you have to search twice. (This may be worse in dynamically typed languages than static ones though, since you have to search on parts of the name of variables/functions/... rather than on the name of their type.) As for the converse case of “synonyms”, where an internal name has been used externally: this tends not to happen as often, as customer support employees and so on are usually less aware of the internal names, though I assume it's confusing for the customers when it does happen.
If you can avoid or fix at least the above two situations, I'm not sure whether you should go as far as to make all the internal names the same as the external ones. There's probably a good reason why the internal names weren't also changed when the external name was made different from the internal one in the first place. In my personal experience, that good reason is the need to support older versions of the product; it could become hard to merge a bug fix from a before-the-names-cleanup version to the most recent version if a lot of code has to be changed.
Its a fairly common problem. A number of projects I've worked on use code names instead of product names (which may not have been decided on at that point), and use wildly different terminology in code than what is displayed to the user. I would probably leave things as-is, unless you're undergoing a massive re-purposing of the code or if there's something specific causing problems. No use in upsetting the apple cart. Also, who's to say 5 years from now there wont be more changes? And then you'd have to go through the renaming again. And dont forget, that also affects any separate code documentation you might have (published API's), which could be a particularly costly issue if its printed (hard copy).
I say fix it in any case where the code is meant to be maintained for any length of time. You'll likely save confusion and time in the future.
I find that often the "marketing" entities don't correspond exactly with internal entities. In such cases, it makes more sense to introduce an entity at a different level of abstraction, which makes the terminology differences a moot point.
For example, we have a model that represents a hierarchy. Each level in the hierarchy has a term associated with it based on how the hierarchy is used to model real-world relationships, but internally there isn't a difference in behavior from one level of the hierarchy to the next. The terminology is essentially just a name for that level in the hierarchy, so for a particular node in the tree the name simply describes what the node is; it doesn't prescribe any particular behavior.
Also, the tree is multi-rooted, so there are several nodes without a parent. Even though conceptually a root exists (it would essentially represent the universe), and including it in the model would many operations much simpler, there is no "marketing term" for it.
Of course, different components in our system use different terminology. They were developed at different times by different teams, and we don't have control over all of them. Actually, at some point, someone added or removed a level in one component, and so the other levels are shifted relative to each other. The same three levels are represented by A, B, and C in one component, but as B, C, and D in another.
Taking a step up in abstraction and simply modelling everything as a "node" or something equally generic makes these kinds of models a lot easier to reason with. Each node knows what its "marketing term" is, and the type that represents a particular marketing term can know what that term means in each context.
