The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Changing the terminology used in your code

A client requested that we change the word "Stage" to "Status" wherever it shows up in the interface.  By changing one line in a language definition file we were able to accommodate the client's request.

Unfortunately we still have references to "stage" sprinkled all over the project in comments, method names, database column names, and all sorts of associated documentation.

Would it be a mistake to leave the references to "stage" in the code?

Are you constantly updating your program when the client changes the language of the domain?
Alex
Friday, December 08, 2006
 
 
I think it would be a mistake to leave it as-is.  In most projects you'll get enough accidental poorly-named and outdated stuff as it is, without leaving in things you _know_ are wrong.

Sometimes there's stuff in your language that will make the renaming easier.  In .NET you can use the ObsoleteAttribute to mark stuff along with a note about the new name; this lets you rename things as you go without breaking anything in the meantime.  You can use regular expressions to find things to be renamed in comments.

Unfortunately, it's rarely as simple as a big search-replace-and-you're-done.  But I'd rather do the work to rename something properly than have confusing terminology in my code.
Kyralessa Send private email
Friday, December 08, 2006
 
 
Not necessarily.  If they are your only customer or your biggest by far, then it probably makes sense to keep everything in sync.  If they're just one customer, it's not a big deal as long as it shows up properly in the UI.
KC Send private email
Friday, December 08, 2006
 
 
This kind of thing happens to us all the time. We do a lot of customization of the base product for our clients. We just live with it now. Yeah, it can easily come back to bite you but you are better off picking "base" terminology rather than changing everything to match one customer's expectations. Because sooner or later another customer will come back and ask for it to be a differnt way and then you are right back where you started.

But I feel your pain. I like code that is "just right" and this type of thing REALLY irks me. But what can you really do?
Turtle Rustler
Friday, December 08, 2006
 
 
Yeah.  I call these things "land-mines".  Places where terminology is changed in the source, but not in the docs, or vice-versa.

I know it's a pain to change it everywhere, but that's the safe way to go.  The safer approach is not to change it anywhere, but with some customers that's not an option.

If you have to change it more than once, though, make sure you bill the customer each time he changes his mind.
AllanL5
Friday, December 08, 2006
 
 
I assume it's a single client and the domain really has changed - then yes - you need to change it everywhere - database is especially annoying.  Otherwise it's just a ticking timebomb before someone misinterprets the field.

That's why nomenclature is so important early on in projects.

If it's just one stubborn client and the domain really hasn't changed and you need to support your best practices as well as their choice of names - this is when your localization/internationalization subsystem kicks in and pays off and that client just gets new naming.
Cade Roux Send private email
Friday, December 08, 2006
 
 
I work on a system where a lot of changes have been requested.  We are changing the names everywhere (with the possible exception of code comments and maybe the occasionaly method or local var name).  We are changing our entity objects, our database etc.

In our case, I think that's the right approach, because with so many changes over the last couple of years it would be a maintenance nightmare if we'd just changed the UI.

On the other hand, if there'd only been one or two changes, then maybe changing the UI alone would have been acceptable.
John Rusk
Saturday, December 09, 2006
 
 
I support an internal app.  When our terminology changes, I change the code.

It is not that difficult for me.  My app is not that big (about 1.8MB of source), and I code in a way that the references can be easily found.

I prefer making the updates to having cognitive dissonance later.  This, obviously, is a YMMV issue though.

Sincerely,

Gene Wirchenko
Gene Wirchenko Send private email
Sunday, December 10, 2006
 
 
>>That's why nomenclature is so important early on in projects.

+1 to that!

If your program process isn't changing, settle on *one* set of terminology in the code & change the labels etc as needed.  Using the OP's example, if 'stage' describes the thing better, leave it named 'stage'.  If 'status' is better, use 'status'.  Give clients the ability to change labels and they'll be happy. 

Re the database object names: if your clients are poking around in your app database to the point that they need to have things labelled exactly like the interface, you're allowing too much access IMO.  If they need to do reporting etc, they should have a data dictionay & views.
(again IMO)

My company's primary app supports users in vastly different industries with widely differing specific uses.  Our code is never changed for a client unless we're adding a GA feature.  They can change labels & enable or disable program features or data elements, but a given release is identical for all clients that use it.  To do otherwise, we'd have to more than double our development group.  We have *real* improvements we want add to our product & the kind of thing the OP describes isn't one. 

my sympathies to all who have to dance to that tune...
a former big-fiver Send private email
Monday, December 11, 2006
 
 
If you plan on internationalizing your application, the general advice is to put all labels and text into a sort of look up table. In this case, you might have something like...

FORM_XYZ_STAGE_LABEL = "Status"

It then becomes easier to give a compiled copy of the program and a "strings file" to someone else for translation into French, Spanish, whatever.

If you find that you're changing labels and text often for your customers without actually changing the underlying controls, this may actually be a better long term approach.
TheDavid
Monday, December 11, 2006
 
 

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
 
Powered by FogBugz