Coding practice: length limit for an identifier

[Joyce Lee]

Below is a snip of the naming convention rules from JavaCodingStandards by Scott W. Ambler (pg 9, point 5). You can download the document here.

5. Avoid long names (< 15 characters is a good idea). Although the class name PhysicalOrVirtualProductOrService might seem to be a good class name at the time (OK, I�m stretching it on this example) this name is simply too long and you should consider renaming it to something shorter, perhaps something like Offering (NPS, 1996).

My question is, what suggested length limit for an idenitifer do you practise at work? Is there a rule you must follow such that you cannot exceed XXX characters for an identifier?

The author of the javacodingconvetion, felt that this class name,
PhysicalOrVirtualProductOrService, was too long. My concern is, different people have different views when it comes to the length limit of an identifier. This may cause disagreement during the peer review between the two programmers if rules are not set. One may feel that the identifer is too long. The other may think not. How should one handle this kind of conflict?

One way of preventing the identifer from getting too long is to the shorter form, e.g. "num" instead "number". But some may argue using "num" would make the code less readable. What do you think?

Any comments are welcomed.

Joyce
[ June 15, 2004: Message edited by: Joyce Lee ]

[Tim West]

My preference is for no length limit. I aim for maximum clarity, the length is a consequence of this rule. In the system I'm working on, names like "RelocationsCustomerFacadeBeanLocal" or "RelocationDetailDAOCmpImpl" are not uncommon, and this is, IMO, an ideal name. Perhaps some are pushing it a little: "CalculateAllowanceAmendTravelTimeAction".

Basically I reckon each part of the name should convey something useful. This includes the fully qualified name - the package can convey part of the "context" of the class, I guess.

Although the author didn't mean the example as a realistic example of a bad name, PhysicalOrVirtualProductOrService is bad for another reason. It suggests that one class is wearing four hats. (The four separate concepts of physical, virtual, product and service). I'd say there are potentially two separate inheritance heirarchies here, and a good use for the bridge pattern.

Anyway, my $0.02.



--Tim

[Jeroen Wenting]

Generally, the more specific the task for a class, the longer it's name.
The longest classname I have so far in my current project is 47 characters, which is caused mainly by my dislike for abbreviations and acronymns in classnames and thus having ToStitchSomePrettyLongWordsTogether

[Joyce Lee]

Thanks Tim and Jeroen for the comments!

Having a long name does help in clarity. But I have a few concerns for long name identifiers.
* if one of the coding rules says, maximum line length is 80, having a long name can easily break this rule.

For example, if

aLongVariableName =
        ToStitchSomePrettyLongWordsTogether.calculateALongNameAlgorithm()
- ToStitchAnotherPrettyLongWordsTogether.calculatAnotherLongNameAlgorithem();

* Hmm...long name also means long statement. I feel it will take a longer time for the third party to read.
* Whoever uses thirty party classes and methods, will need to spend time typing the name.

All right, now, how long is considered long? Does anyone of you have a rule on this? :

Joyce

[Mike Gershman]

I don't see how there can be one rule.

Code that will be seen by many people, especially the public part of class definitions, could gain a lot from the self-documenting aspects of fully explanatory names.

Code that will only be seen by a programmer who learns the code thoroughly might benefit from more brevity.

One warning about using long identifiers as comments: if the code changes so that the meaning of a variable changes, you may be tempted to skip changing every use of the identifier. Now the identifier is misleading.

[Ernest Friedman-Hill]

Originally posted by Mike Gershman:


One warning about using long identifiers as comments: if the code changes so that the meaning of a variable changes, you may be tempted to skip changing every use of the identifier. Now the identifier is misleading.

Modern tools leave no excuse for this kind of laziness; renaming any class, method, or variable is only one click away in an IDE with refactoring features.

Regarding Joyce's point about 80-character line lengths: we had a recent thread about this, and found that most respondents were either not using a formal limit, or using a limit closer to 120 or 132 characters. But yes, it does seem that if you have a strict rule about line lengths, you'd have to also have a rule about identifier lengths; that's a good observation.

[Mike Gershman]

Modern tools leave no excuse for this kind of laziness; renaming any class, method, or variable is only one click away in an IDE with refactoring features

That works for non-public code and for code residing in one site, but if the class is used in other sites, even other enterprises, each change to the public interface is a big deal. Even if the revised class is downward compatible with the old version, changing a public identifier means that many more users must change code using the class.

Yet the public interface to a widely used class is the ideal place for highly descriptive identifiers.

I know I'm arguing both sides of the question. That's my point.

BTW, do these IDE's remerge identifier changes into modules that were copied from the shared library for editing, etc., and then returned in updated form? Do Java Beans facilitate this?

[Stan James]

I use a framework that is likely to say:

fully.qualified.package.ToStitchSomePrettyLongWordsTogether myStitchSomePrettyLongWordsTogether 
    = (fully.qualified.package.ToStitchSomePrettyLongWordsTogether)ToStitchSomePrettyLongWordsTogetherFactory
    .getToStitchSomePrettyLongWordsTogether("fully.qualified.package.ToStitchSomePrettyLongWordsTogether");

I don't recommend the practice.
[ June 18, 2004: Message edited by: Jim Yingst ]

[Jim Yingst]

Sorry, Stan, I had to insert some line breaks so that your overly long line didn't screw up the formatting of the rest of the page. Which I guess is a good illustration of why really long identifiers can be a problem.

I've never used (or been subjected to) a hard limit to identifier length - but I'd say that it should be somewhat less than half your maximim line length, so you can comfortably write.

ModeratelyLongClassIdentifier mlci = new ModeratelyLongClassIdentifier();

[Warren Dew]

I prefer not to use identifiers that don't fit on one line. On the other hand, I have no problem with the following reformatting of your code above:

aLongVariableName
    = ToStitchSomePrettyLongWordsTogether
        .calculateALongNameAlgorithm() 
    - ToStitchAnotherPrettyLongWordsTogether
        .calculatAnotherLongNameAlgorithem();

I actually think that breaking up statements and expressions into multiple lines can make them more legible, rather than less. If you keep all the operators at the beginnings of lines, as above, a quick glance will reveal the structure of the statement; you can then read the variable names in detail if you need more information.

At one point, working with a language and compiler that had a 31 character length limit on identifiers, I got in the habit of limiting my identifiers to 31 characters. That was actually somewhat constraining, though, as it forced me to use abbreviations. The abbreviations sometimes resulted in ambiguity, so I now have a strict rule against using abbreviations.

Joyce:

* Whoever uses thirty party classes and methods, will need to spend time typing the name.

One can always cut and paste.

This may cause disagreement during the peer review between the two programmers if rules are not set. One may feel that the identifer is too long. The other may think not. How should one handle this kind of conflict?

Unless there is a written and enforced coding convention that one of them can point to, I always consider the review advisory and the author of the code to have the last say. I've found that this policy leads to more productive reviews as people quit using them to try to fight religious wars and instead start focusing on finding bugs and providing constructive advice that the author will actually find useful.

Ernest:

Regarding Joyce's point about 80-character line lengths: we had a recent thread about this, and found that most respondents were either not using a formal limit, or using a limit closer to 120 or 132 characters

That was the thread I started, right? I actually posted that poll because I was trying to decide between line lengths of 72 characters and 80 characters, myself.

I realized in reading the responses, though, that most of the respondents don't use their screens like I do. Most people seem to just maximize their editor and use the full screen width for one file at a time. I personally like to be able to have two or even three files open side by side, making a shorter line width more important. So I guess the poll didn't help me as much as it could have, though I'm glad someone else remembers the thread.

[Warren Dew]

Er, Stan, your framework requires fully qualified names and doesn't allow you to break statements into multiple lines? I guess I'd consider switching frameworks....

[Stan James]

The vendor wrote fully qualified names in all their code. Eclipse will offer to add an import and remove the full path from one reference, but not all of them. That might be a nice refactor to put in some day.

I have no idea why the vendor chose that style. If you convert them all to imports and see how many imports there are it makes it very obvious how many freakin dependencies their classes have on each other. Kinda nasty. Anyhow, it makes things very difficult to read. You have to parse carefully for classnames and spaces for variable names. Yuck.

BTW: The vendor doesn't do that any more. They use import in new code. But their names are still fairly ridiculous. I told the team not to compete with the vendor for long names 'cause we'll all lose.

[Warren Dew]

by Stan James:
The vendor wrote fully qualified names in all their code... I have no idea why the vendor chose that style.

I bet they came from another language where it made sense. In C++, for example, the include mechanism is such that it can be difficult to find things unless you use a fully qualified name. I know someone who works primarily in Ada whose team also ended up always using fully qualified names, probably for similar reasons.

The nice thing about the Java import system is that one can always tell exactly where everything comes from by looking at the import line, provided each class is imported individually - someone did some good language design work there. It took me a while to get used to never qualifying my names when I first started using Java, but it's really nice now that I'm used to it.

[Tim West]

I know this is slightly OT, but does anyone else find this sort of debate difficult to take seriously when the examples given are so fake?

What I mean is that you'll never see a class called "ToStitchSomePrettyLongWordsTogether", and so debating whether or not it's a good name is pointless. You may as well consider the class "ImRunningDownTheShopsToGetSomeMilk".

IMHO, examples need to be realistic. In this case, we should use class names that, even if they don't exist, could: they seem realistic. This means that they're nouns (as classes should be), probably with some prepended adjectives or even a verb. Then we can consider whether the name is overly-long, or whether there is another problem. A perceived problem in length could be caused by a few things.

As I mentioned earlier, that you should never have a class with this name because it's a poor abstraction: it should be two or more classes.

The class name contains superfluous words, ie, ones that don't add any information to the name.

The class has a "good" name but it happens to be very long due.

Others?!

As I see it, this thread deals only with the third category, but uses examples that aren't even decent class names.

Anyway, had to ask . I have a vague memory of one eminent author who carried the "torch" of meaningful examples, but I can't remember who it was.

Any thoughts?


--Tim

[Warren Dew]

Okay, I dug up an example. This is from 'way back on a project that was using 31 character file name length limits, restricting class names to 26 characters. This name ended up being ambiguous because of the length limit:

TradeLayerCompJUnitTest

Is "Comp" "Component" or "Company"? Both Trade Layer Components and Trade Layer Companies existed in this project!

In retrospect, it would have been better to drop the "Test" from the end and use "TradeLayerCompanyJUnit".

[Jeroen Wenting]

I chose that name as an illustration only and it stuck so obviously I did get my point across

Maybe a better example (but then you might complain that I'm being too specific) would be ToshibaBarcodePrinterModel5000Mod2 extends ToshibaPrinter implements BarcodePrinter.

Could shorten that to TBP5000M2 extends TP implements BP but that would be kinda cryptic.

[Stan James]

We had things like ProjectNameCustomGenericRequestHandlerServlet extends VendorNameAbstractGenericRequestHandlerServlet. A lot of the vendor's names included the package name or the base type. Like putting "servlet" in the name of a servlet. Yuck. So, yes, they really get that long in the wild. Makes it nearly impossible to write a meaningful statement on a single line.