How far should we rename code and data when end users nomenclatures change?

Question

A long time ago we added a feature where our users could "Accept" an image after it was added to a workflow queue. Turns out, we used the wrong term, and users actually "Approve" the image.

Changing Accept to Approve on our interface is easy, just replace one word. But we programmed all layers with the word "accept", from the CSS class name to the database values.

• The CSS class that turns the button green: ".accepted";
• The model method that verifies and binds the class attribute on the DOM node: "isAccepted";
• JavaScript status attribute: Array with "unreviewed", "accepted" and "published";
• Mysql status column: ENUM with "unreviewed", "accepted" and "published";
• Test names;

It's trivial (specially when you have tests) to replace most occurrences of accept to approve. A little bit harder is to migrate the data, specially since it needs to be synchronized with deployment.

This specific case is simple, but I've faced similar, yet more complex cases, during my career. When a file is also renamed and deployment happens on dozens of servers, or when proxy caching, memcached and mysql are involved.

Leaving "accepted" on every other layer except the interface is a bad idea, since new programmers joining the team might not learn the historical reasons it led to this decision, and while accept -> approve are close words in terms of meaning, if it was renamed to "queued for managerial next status meeting", it certainly wouldn't make any sense. And it feels if we compromise here and there, in a few iterations the user interface concepts will have no bearings to the system internals, and I certainly do not want to work on a system where half of the output has no connection to its innards.

So, do you always rename everything when needed? If this happened to you, and you decided that the trade-off was not worth, did it come back to bite you? Is code comment or developer documentation enough to avoid this issue?

Answer 1

For me, it is definitely best to change everything related to the item in question.

It is a form of code degradation, and while 1 item not being changed might not be a big deal, it sets the tone for the code base.

It could also lead to confusion in the future and make it harder for new devs to understand the code base/domain.

Answer 2

From the question content and tags I'll assumer you're using ubiquitous language.

In my experience UL is great but, as you mentioned, can lead to additional maintenance tasks as the language evolves. This, in itself, isn't a bad thing. Sure, it's inconvenient, but it's also expected.

What I've typically done (and seen done) is either:

• 1-shot upfront refactoring: Refactor all layers of the application to adopt the updated language; or
• log technical debt: You can change user-facing code right away, and then log technical debt tasks to bring the rest of the application layers in line with the updated language. This typically results in a handful of boring (but manageable) tasks. (Perfect for 5pm!)

I think the key thing here is that what you're describing is technical debt and should be recognized as such.

I've had managers who've argued that we shouldn't be wasting time on such trivial tasks that don't add any visible functionality. This is when the debt analogy really comes in handy. It boils down to this:

The team chose to do DDD with Ubiquitous Language. Straying from this approach by leaving the code in an inconsistent state adds confusion and removes many of the benefits that DDD and UL provide. In manager terms, it adds cost to the project. The code becomes more difficult (expensive) to manage, and more confusing for new developers (expensive).

Answer 3

You may want to look into Localization (l10n) options. While it may not seem as drastic as going from English to Spanish, you're dealing with a different term for the same concept. If this seems to happen commonly, then using l10n can allow you to quickly change what is displayed in the user interface while not having to change the term used in code.

With that in place, just use the terms in your code that are the most widely understood. Choose names from the domain as developers know it and might expect it.

Answer 4

As you appropriately depict this, tracking end-user nomenclature changes in every part of the source is quite an investment. It is however definitely worth it, especially for a long living product developed by a complete infrastructure (with hotline, testers, etc.)

Tracking end-user nomenclature in source is an investment is because there are so many component types where it appears and there is no magic wand working simultaneously on all these components. Maybe developing such a magic wand, component after component, is an interesting investment that you can dilute over the lifetime of the project.

I worked on a 30-year old codebase where the drift between end-user nomenclature and internal nomenclature grew especially large. Here are a few drawbacks of this situation, which all add to the overhead of everybody's work:

1. In the absence of an adequate policy, new development tends to use the current end-user nomenclature. Thus, the same concept may have two or more names in different components. Since the components interact together, this results in several synonymous names existing simulatenously in some local parts of the code.

2. When the hotline/help desk is called, they write down a user story using end-user nomenclature. The developer in charge of fixing the problem must translate the end-user nomenclature to match the source nomenclature. Of course it is not archived, and of course it is a mess. (See 1.)

3. When the programmer debugs the code, she wants to set breakpoints in relevant functions. It is hard to find the appropriate functions if the end-user nomenclature and the source nomenclature do not agree. It might even be hard or impossible to be confident that a listing of the relevant functions is even complete. (See 1.)

4. In absence of an adequate policy, maintainance of source using an obsolete nomenclature will from time to time put this obsolete nomenclature in front of the users again. This produces poor impression and causes overhead.

I already tracked down two days long the very place where some data is read off the database and injected in some component of this codebase. Because whether I nor anybody at the company I worked was able to figure a name leading to this place I finally dismissed and decided to find another solution to that problem.

While costing more than[1] two days of maintenance without yielding anything (no knowledge, no fix, nothing) is probably as bad as it can get, discrepancies between user-nomenclature and source nomemclature add overhead to many routine task in the maintainance of a software.

It is important to remark that the overhead cost grows with the company producing the software, in a large organisation, a problem report will not arrive on your desk before it has been considered by several colleagues and the fix might be subject to test.

[1] Because of more than one developer being involved.

Answer 5

I don't always rename code and data because some packages are shared between customers. They are basically using the same thing but call it differently. Examples, in a CMS, one client calls their customer "Customer" and another uses "Client". So we replaced Customer with Client on the surface for one client, but CMS will always be a Customer Management System.

Another example is User management with terms like permissions vs access control list, admin vs manager, etc. It can be confusing to new comers but for core components like those, there are usually core developers who make sure that those components work for all clients and also easy to implements by other developers (e.g. by creating configurable labels).

It might help to think that if you do make this change, hopefully you won't need to do it again if the same piece is used by other customer, basically turning it into a product.