Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

How important is naming consistency?

 
John Willeams White
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
With regard to the SCJD assignment, which I'm about to register for, I have an upfront question about the importance of keeping names consistent. This may sound like a dull quesion, but I'm really doubting about this.

In the URLyBird assignment there are a couple of problem domain names mentioned, like for example: room.

Now I wonder whether I -have- to use this exact term in both the source code and the userinterface. And even if I don't -have- to use it, would it be considered good practice to do so or not?

For example, suppose I would like to use the term chamber instead or room in my code and create an interface like ChamberManager with methods bookChamber and findChambers, but use the term room as text in my interface. E.g. "The system is now looking for free rooms", would that be ok, or would that be bad practice?

I started doubting about this when reading some posts in this forum about retrieving the userinterface text from a resourcebundle. If the text for the userinterface comes from such a bundle, it means there is a decoupling between the code and the text being displayed. Although the assignment doesn't ask for it, it would theoretically allow changing languages. Now if we change the language, the term being used in the code ("chamber") would of course not correspond anymore to whatever is used in the userinterface.

So, taking that idea into account, would it be better to use different terms in code and in the userinterface (even though both happen to be in the same language, namely English), or would it actually be better to just use the same terms?

To sum up:

Constants in bundle:
sun.assignment.chamber = room
sun.assignment.freeChamberSearching = The system is now looking for free rooms

Java:
interface ChamberManager {
void bookChamber();
}

vs

Constants in bundle:
sun.assignment.room = room
sun.assignment.freeRoomSearching = The system is now looking for free rooms

Java:
interface RoomManager {
void bookRoom();
}

Of these two, which would be the preferred version?
 
Alex Belisle Turcot
Ranch Hand
Posts: 516
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,

let me give you my personal opinion..

On an object oriented perspective, If I look at my domain model, I might realize that 2 words can be used, Chamber and Room. Maybe they don't have the exact same meaning, possibly internally the client uses Room but advertise "Chamber" to its user.. Then it *could* make sense to me to develop using Room, and display "Chamber".

Then, you could also create a glossary to define those words.

However, for this assignment, I consider SUN to be my client and for the sake of clarity I use the same word everywhere.

For instance, I use the word "Find" and never "Search".. That's just me.

If you tend to use a different word, maybe you think they have a slightly different meaning? Maybe they do have different meaning.. Maybe Room refers to something more abstract than a Chamber? The database could handle any type of Room and the GUI only display Chamber type? (I have no knowledge of your assignment details..). A kitchen would also be a Room but not a chamber?

My 2 cents.. I would like to hear what others have to say about that..

Regard,
Alex
 
Alex Belisle Turcot
Ranch Hand
Posts: 516
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,

me again...

I wanted to add, in my own opinion, the system should be :
- developed using the client's vocabulary;
- displayed using the users' vocabulary.

the client being the one paying for the system and maintaining it afterwards

I would definitely like to hear others on that!

Alex
 
R van Vliet
Ranch Hand
Posts: 144
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I agree with Alex, especially if a functional specification exists that specifically and consistently uses the same word for a certain entity.

I also agree with Alex' second post in that the vocabulary used to present information to the user may definately differ from that used internally. In almost all cases this is due to the internal names being technically more accurate or descriptive. That said, I think in the case of "room" there is no need to use to seperate terms.
 
Arjan Times
Ranch Hand
Posts: 35
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

That said, I think in the case of "room" there is no need to use to seperate terms.


I had the same discussion with someone about this subject. For the past week I've been reading a lot about software designs and most literature seems to suggest that indeed if the user vocabulary is "room", than the class names and methods in the implementation code should also be simply based on "room".

Originally posted by R van Vliet:
I also agree with Alex' second post in that the vocabulary used to present information to the user may definitely differ from that used internally.


I think the emphasis should be on "may". Indeed, it may be different, but it certainly does not have to be different. In fact, making the terms different apparently is more of an exception. I.e. something you resort to when there are very good reasons to do so, but not something you start out with.

Everyone else has anything to add to this?
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic