I've been noticing in some posts from other college students that identifiers and, at times, indecipherable to me (another Java Beginner). My textbook and the three Java for Dummies books I own indicate that identifiers should be meaningful. Obviously, the experienced people here on Java Ranch understand the identifiers, because their understanding of Java is far greater than mine. It's similar to be able to untangle someone's typos (in English-language posts) when you are fluent in English.
Anyway, my question is this. (Yes, I know you were wondering when I would get around to it.) In the Real World of Programming for a Living, what are the guidelines for creating and/or using meaningful identifiers? For example, I've worked in Retail, therefore I know that stock isn't something you buy through a broker as an investment; it is synonamous with inventory. Also, Cost is the same as Price but both are ambiguous, as you can have wholesale, retail, or sales prices/costs.
I created identifiers like retail, salesPrice, unitCost, and inStock because of my past experience. However, my instructor gave examples of code with identifiers like cost. Now, I don't want to waste my time nitpicking something that is a waste of time. I really just want to understand.
Any advice, suggestions, or other pearls of wisdom (as I do not count as swine, these are safe to dispense )?
Disclaimer: The author of this post makes no claims, implied or otherwise, as to her ability to understand anything but the simplest of answers. Further, the author of this post has no programming background whatsoever and has taken one Java Programming class which was 9 weeks long. She does want to learn, so please teach patiently.
An identifier should be 'just right'. Not so long that you get tired typing it, but long enough to be unique and understood. For example, if you have only one value that is a cost, as your instructor probably did, 'cost' is probably Good Enough. If you are working on code that deals with wholesale, retail, discounted and sale costs, you will need more explicit identifiers. One-letter names ('i' or 'x') are Good Enough for temporary values like loop indexes that have no other meaning.
The most important criterion (IMO) is to think how your class, field and method names will read in your code. Well-chosen, meaningful identifiers will effectively self-comment the actual code minimizing the need for additional code documentation. Good code should read almost like English. If one word is adequate to represent something, then that is what you should use. Otherwise, add additional descriptive words.
That said, my rules of thumb for naming are these:
1) Use the terminology associated with your domain (business environment). If your business uses the term "stock" for "inventory" then that is what your code should use. I attempt to code such that, if a business analyst looks at my code, he/she can readily make sense of it (without necessarily understanding the particulars of the code).
2) Identifiers should be exactly what they represent. Avoid ambiguity. This goal is not always achieved in the first iteration but the great advantage of modern IDEs is that you can easily refactor/rename to do so.
3) Identifiers should rarely be more than 3 words, not counting "get" and "set" for method names.
4) Identifiers should ideally be 1 or 2 words. Keep it short (but within reason).
5) Avoid using long words in identifiers. I try to avoid words over 8 characters in length.
Don't think you have to get it right the first time! I've been coding for some 27 years now and I still frequently change my mind regarding the names I have chosen. For that reason I love the refactor options in Eclipse/RAD!
Joined: Apr 30, 2008
Joe and Jay, thank you! Wonderful advice, and I really appreciate it. It makes sense, its easy to understand, and simple to follow.
I’ve looked at a lot of different solutions, and in my humble opinion Aspose is the way to go. Here’s the link: http://aspose.com
subject: Identifiers: Inscrutable versus A Little Longer?