Very Long Descriptive Names That Programming Pairs Think Provide Good Descriptions

I think the intention of the original author is to mock. Maybe an IronyWarning badge is needed.

Long names may imply that the programmer or the pair didn't understand what they wanted to do or the code is too complex. A lot of programmers think that long names are more descriptive than short. That is not true. The names have to state what is inside the variable and not more.

Just because you understand something doesn't make its name short. Some things just have long names. Abbreviating them can be confusing.

How about a VeryLongDescriptiveNameAbbreviationChallenge?

perhaps the challenge should be to simplify the concept so that the long name is no longer necessary

You make naming easier by giving a concept more context. There are a number of refactorings that make this possible; I often find myself using ExtractClass to a MethodObject. So instead of a User class having a method called updateExpirationDateBasedOnLastPayment, you might extract a lot of that code to a MethodObject called ExpirationDateUpdater, with a method called useLastPayment. The method name can now be shorter because the new class name carries some of the explanatory burden.

This is how spoken language works, as well: If you hear a word without hearing the rest of the sentence, you often won't to be able to figure out what that word is supposed to mean. -- fh

Some names are long regardless of context or simplicity/complexity of "the concept". It's simplistic to claim a long name indicates lack of understanding. I'd rather say, "Strive for the shortest name that conveys the authors intent."

I don't think I'm any better than anybody else at automatically finding short method names, but in the times when I bother to persevere at it I almost always find that I can keep refactoring until I get a short name. Aggressive refactoring is what does it for me, that and having no fear of having LotsOfLittleClasses. If this doesn't seem right to you, it might be useful for you to offer an example so we can compare why our experiences are different.

Example:
 InternationalizationConvention aHarmonFiddleWatleyAndSprungInternationalizationConvention = new HarmonFiddleWatleyAndSprungInternationalizationConvention();
 InternationalizationConvention aGreblitchBorgFungalInternationalizationConvention = new GreblitchBorgFungalInternationalizationConvention();
The classes and variables have long names because the things they represent have long names. Understanding them doesn't make them shorter.

That wasn't the sort of example in mind, not least because I don't understand what this code's supposed to do. It's supposed to instantiate two different implementations of InternationalizationConvention. But I'll bite anyhow. To start with InternationalizationConvention: How many classes does such a system have that are related to the issue of Internationalization? If it's a handful, then you can cluster them into some namespace. For example, in Java, you might be able to define these classes as belonging to com.myowncompany.internationalization ... Then your Java code would look like:

 include "com.mycompany.internationalization.*"

class SomeClientClass { public void someMethod () { Convention aHarmonFiddleWatleyAndSprungInternationalistConvention = new HarmonFiddleWatleyAndSprungInternationalizationConvention(); Convention aGreblitchBorgFungalInternationalizationConvention = new GreblitchBorgFungalInternationalizationConvention(); } }

But they aren't Conventions, they are InternationalizationConventions. Let's say they are part of a practice called com.mycompany.businesspractices.

Hmm ... how about
    class SomeClientClass? {
        public void someMethod () {
            // This code does stuff with xyz conventions.
            // What they are is documented in xyz.pdf
            Convention aHarmon = new Harmon();
            Convention aGreblitch = new Greblitch();
        }
    }
Since hopefully the maintenance programmer will at least have a vague clue about what this program is supposed to do, and should have access to one person with a least a little business knowledge of the problem. BTW I'm assuming that Harmon and Greblitch each have taken part in only one existing convention. The exact convention title, date, specs can be summarized in the appropriate class header for reference inside the code. -- RM

Now, obviously for this to work, you have to be careful that your class' responsibility is very small, so the chance of overlapping meanings for "Convention" is reduced. Also, I'd wonder if there's a more specific word for that class instead of "Convention" -- but not having any idea what an InternationalizationConvention does at all, I personally wouldn't be able to suggest one myself.

A convention is "a practice or procedure widely observed in a group, especially to facilitate social interaction". An internationalization convention is a convention used by a group to internationalize something.

Goodness, I know what a convention is. I just don't know what this specific convention is supposed to accomplish. Some words are more specific than others. Convention to do what, exactly?

Internationalize something. There are two different ones modeled in the code. What they do isn't important to the discussion. Some things have long names. Shortening neither increases readability nor indicates understanding.

I find this to be a curious statement: "What they do isn't important to the discussion." Shouldn't the names of classes naturally flow from their specific functions? Or are you working in an environment where the names of classes are set in design documents and domain models? Are you working more bottom-up or top-down?

In the example the names are taken from the ProblemDomain (our revealing pet name for the world outside the computer.) The code is manipulating different kinds of internationalization conventions. The specifics don't matter; I just made them up to show that sometimes the names of classes or methods flow from real world names, and sometimes real world names are long. Sometimes abbreviation obfuscates intention. Names shouldn't be short or long. They should be as short as they can and as long as they must.

I'd wonder about the ability of inner classes to kind of make namespaces hierarchical, so at least the namespace would take some of the naming burden off of the class name's shoulders. I can't remember off-hand if Java InnerClasses would help so much or if they're cumbersome like so many things in that language. In my language of choices InnerClasses are a cinch, so I use them all the time.

I wouldn't use an inner class to avoid typing a long name. Brevity should not dictate structure. My IDEs all have auto-complete, making long names easy to type anyway.

Another related issue is the extent to which you're allowed to abbreviate in your class names: Some people wouldn't like to abbreviate InternationalizationConvention to I18nConvention. But most people will name a class XmlElement instead of ExtensibleMarkupLanguageElement: It all depends on who your target audience is -- that is, the other programmers reading your code -- and how familiar they'll be with such abbreviations.

I don't mind "XML", since that's a standardized acronym. "i18n" is just lazy. It's easier to type but harder to read. For our example we could use another term that doesn't have a widely used numeronym, even one that collides with i18n.

And if you use Java, it's gonna be verbose no matter what you do. -- fh
Don't most people know that I18n is internationalization?

Maybe, but everyone knows that internationalization is internationalization. What advantage is there in using the numeronym? Saving calories while typing? Saving bytes in the source file?

AmericanCulturalAssumption! We Brits know that internationalization is actually internationali_s_ation. :)

i18n is well established industry jargon which serves both to abbreviate a long term and remind you of the differences between American and British English that can bite you during i18n of a software product.

Also, how is a Strategy different from a Convention save that Strategy is shorter?

''And I was totally confused as I though Convention was a meeting of similar minded people - I didn't realise it the other meaning of the term convention . . . . . so even the long name didn't manage to convey what it was supposed to.

InternationalizationConvention is the domain term in my example. It could be anything with a long domain term. Don't get hung up on specifics.

Finally, is it important for the variable name to include information about the concrete subclass? Shouldn't the variable just be something like anI18nStrategy? I don't often type:

 List anArrayList = new ArrayList();

I do. And in the example it is important. The reason those variables exist is to be instances of different internationalization conventions. Keeping track of which is which is important. I don't want to call them i18nC8n1 and i18nC8n2.

Personally, I think the above long names are pretty atrocious. Just horrible. Spelling them out does not help me in any way to figure out what they actually mean. If I did know what they meant, I wouldn't need the completely spelled out names.

Spelling them doesn't help you figure out what they mean, but if you're the author it is assumed you already know. Reading them will help your audience (other developers) figure out what they mean. Anyway, screens are big, bytes are cheap and IDEs have auto-complete.

Maybe it's just me, but this conversation seems to have drifted into polarized silliness. The original point, which was that a long name can be a signal to look deeper and possibly refactor, is well taken.

Is that the original point? The one I read seemed much more absolute.

The followup, which is that some things are just complicated, is also well taken. I find that four (or more) word names are typically a sign of problems in my code. "Let every word tell." -- JimLittle

I'm finding this conversation useful, myself, though the argumentativeness of it could be refactored out. -- fh

why do you need to know what type of InternationalizationConvention a variable is? why do you care if that convention is HarmonFiddleWatleyAndSprungInternationalizationConvention or others? If you want different behavior for each convention, why not use polymorphism and put the behavior in the class it self. IMHO, the class name Convention in package com.mycompany.i18n is fine. If you devide part of your code clearly, There's only small part of the code where the class from two package conflicts.

If I was a talking to someone about Internationalization Conventions (disclaimer: I don't know what they are either), I expect I'd start referring to them as "ICs" at around the third mention of the term. I fancy this would actually help me make myself understood. Shouldn't my code follow the same pattern? -- hr

Name collisions increase as name length decreases. "IC" is a common acronym for "integrated circuit". During initial development it is common to become so immersed in terms that their abbreviations seem obvious. During maintenance, however, additional effort is required to translate unfamiliar abbreviations. Code editors can make using long names as easy as using short names, so the benefit to maintenance should be the deciding factor.

For example, right now I'm coding a reader/writer pair for an ANSI standard transmission format. The names used in the standard document are verbose. There's a strong temptation to shorten them, but I'm using the official names as a gift to the next programmer who modifies this code. When the standard changes there will be no guessing about which variable in the code represents which field in the spec. They will have exactly the same name. I only have to type in the long name once. The editor auto-completes it for me after that. The benefit far outweighs any cost. The code is no less readable during initial development, but far more readable during future maintenance.

Anyway, screens are big

There's a reason why newspapers are laid out in columns. By the way, why don't we have BreakableIdentifiers??

 InternationalizationConvention aHarmonFiddleWatleyAndSprungInter-
                                    nationalizationConvention
     = new HarmonFiddleWatleyAndSprungInternationalizationConvention();


If you don't like the name, refactor

Names don't have to be cast in concrete. If the name is too long, not descriptive enough, hard to distinguish from another name, etc., just refactor it. If you don't feel like typing in a long name when writing code, use a short name to get everything working, and then replace it with a better name. I usually find that names undergo changes during development to make them clearer or more appropriate, so don't get hung up about names. Pick one and you can always change your mind later.


Ironically, this page has the longest WikiName on WardsWiki. (2005.08)

I think the intention of the original author is to mock. Maybe an IronyWarning badge is needed.
See also AreLongAndDescriptiveRelated.
CategoryNaming

EditText of this page (last edited January 8, 2010) or FindPage with title or text search