Naming app entities after DB tables

Question

Our app is marred by some really, really horrible naming decisions. It's largely because the team is Russian-speaking and not everyone knows English.

For example, we have a table called POLICE that actually stores policies (as in "insurance policies"). Or we have a table called ACTION that refers to special offers or discounts (I guess because the Russian word "акция" looks like the English word "action").

I may propagate those naming decisions by naming application types the same way. It doesn't apply to data classes only. For example, we have a class called ActionDlg (like, a GUI modal dialog).

Should I, as a developer, prioritize:

1. Clear mappings between DB entities and my application types by naming them accordingly.
2. Or my sanity and name application types reasonably — even though it may cause confusion as corresponding DB tables would not be obvious (I can add javadocs but still).

Answer 1

The trouble with #1 is the mappings are not actually clear. The mappings from DB table to class are clear, but the mappings of those names to real concepts are muddled, inaccurate, and downright confusing.

Go for #2: save your sanity.

And introduce a #3: comment judiciously to clear up why the Policy class is mapped to the POLICE table, even if the comment is little more than // this table should have been named "policy" but they named it POLICE for some reason — at least you acknowledge to future maintainers that the name is confusing. Probably shy away from judgmental comments like // should have been named "policy" table but they didn't speak English.

This strategy pushes the confusing names out of your day-to-day interactions with the codebase. Yeah, it will be a head scratcher when you need to do database stuff, but to be honest, I would never get used to the "policy" table being named "police" no matter how long I worked on the application. I would always need a translation.

Answer 2

I'd propose a third option. You have a specific type of technical debt, which Scott Ambler wrote about as "data debt". If your application still has a long life ahead of it, I'd consider applying database refactoring (there's also a book, in the style of Fowler's Refactoring book) and data repair techniques. You can bring actual sanity to the structure of your application and reduce the long-term costs of developing new features or maintaining existing functionality.

If your application is in maintenance mode or until you finish applying the refactoring and repairs, then I'd suggest Greg Burghardt's suggestions. However, these approaches will continue to incur long-term development and maintenance costs.