Uncle Bobs Naming Conventions

From:  "Robert C. Martin" <rmartin@o...>
Date:  Wed Sep 20, 2000 1:18pm
Subject:  RE: [XP] Class variable and argument names

I use a set of prefixes to separate instance variables, class variables, arguments, local, and global variables.

global int GnumberOfMarriages;

class Person
{
public:
virtual void Marry(Person theSpouse)
{
  Person aPreacher;
}
private:
double itsHeight;
bool isMarried;
static int theirPopulation;
};

The above shows the convention. Globals are prefixed with capital G. Instance variables are prefixed with 'its' unless they are boolean in which case they are prefixed with 'is'. Arguments to methods are prefixed with 'the', and local variables are prefixed with 'a' or 'an' as appropriate (write aPerson but anIterator).

I add one other simple rule to this convention. If a method is short (as nearly all are) and if it makes sense to use single character argument or local variable names, then I will.

void f(int n)
{
for (int i=0; i<n; i++)
f_it();
}

It seems to me this is just a variation on HungarianNotation...

Except that it makes the code read more like prose, not less. I prefer to use "a" for both parameters and locals, to use "the" for members and finally "theOnly" for globals. I admit that Bob's way makes more sense, but I think that my way reads better. -- PhilGoodwin

OK, but the end result is that you are including type and/or scope in a variable's name. I'm not saying this is bad, I'm just pointing out that people who use HungarianNotation every day probably feel that their code is perfectly legible. I do agree however that your way does read about 3 million times better than HungarianNotation.

We are declaring intent in the variable's name. And because many classes of variables have the same intent, we use the same notation for all of them. OnceAndOnlyOnce. -- PhlIp

RubyLanguage has a similar naming convention, mostly enforced by the language. Local variables and methods begin with lowercase letters. Classes, modules, and constants begin with uppercase letters. Globals begin with a $, and instance variables begin with a @. Class variables begin with a @@. And, optionally, functions that return booleans end with a ?. Similarly, instance methods that modify the object are expected to end with a !. They provide valuable hints to a code's intent, without adding extra words to symbol names. -- NickBensema

And I thought this page was intended to be a sarcastic treatise on naming conventions a la Andy Tannenbaum's comment on standards: "The great thing about standards (read: naming conventions) is that there are so many to choose from" (paraphrased).

I prefer no hungarian warts whatsoever. They are simply not needed. The "theMyVariable" thing decreases readability to me, as it always reads in my head with the emphasis on "the" as in THEvariable. The important thing is not the "the" but the variable name itself. It is more clear to use this.variable to distinguish between class instance variables and local variables... and you only even need to do this in methods where there is a name clash. Otherwise, I just use the class instance variable name alone. -- JohnPerkins

I used to use the "this." prefix and disrespect hungarian notation until, I kid you not, an hour after complaining about HN to my boss I spent way too much time finding a bug where I had forgotten to use the "this." prefix. And it wasn't even the first time I had written a bug like that. The problem with "this." is that it's usage is mandatory and forgetting it does not always produce syntactically invalid code.

I still do disrespect hungarian notation a lot but I have adopted the "m_" prefix for instance variables, "s_" for class variables and no prefix for local variables.

I've dropped just about all scope related prefixes. When you get down to methods that are only about 5 lines or less, you either see the variable in the method signature or you don't. If you don't, it ought to be an instance variable, not something from an superclass. If I think that I need a global variable, I prefix it after a bit of self-flagellation. -- MichaelFeathers

Ought to be an instance variable??? Or maybe it is one from a superclass. Maybe it is a class variable, maybe an application global one. Maybe no variable at all, but a macro. Basically you cannot say what it is unless you find out where it is declared and how it is declared, and this look-up is a waste of my time, if two or three letters on the variable name had told me immediately what kind of variable that is. The only variables you don't need to prefix IMHO are local variables of the method; and I'd consider parameters of the method to be local variables, too (because in fact, that's what they are on compiler/interpreter level in general, they just have a preset value). However, instance variables, class variables, global variables and constants should always immediatly somehow be recognizeable as being either one. -- TGOS

Methods that are five lines or less is the key here. Naming conventions address the symptom (no longer knowing what a symbol names, why it's there), not the problem (the code is difficult to understand, therefore badly written). The solution to the problem is to refactor the code. Long methods and big classes are likely culprits if the desire to add prefixes arises.

Using its is interesting. I've always thought that the . in languages like CeePlusPlus would make rather more sense if it were an apostrophy-s [apostrophe]. So rather than a.b() one would use a's b(). Which has less connotation of navigating a static structure than of requesting something of the object. AppleScript does something like this when it says "set the moved_file to move file "Art.gif" of folder "Working Images" of folder "Projects" of startup disk''. -- KeithBraithwaite

Actually, in some situations in AppleScript you can actually use 's. For example, set AppleScript's text item delimiters to "foo" (functionally equivalent to set text delimiters of AppleScript to foo). Doesn't work with named objects though -- no startup disks's folder "Projects"'s folder "Working Images"'s file "Art.gif" -- JerryKindall?

Motivated by interest in JapaneseLanguage, I sometimes read the . (inwardly, not aloud) as "no". -- KarlKnechtel

This is like my reading of -> in CeeLanguage/CeePlusPlus. Before learning these languages, I programmed extensively in Pascal, where one writes ^. (i.e. as in objectPtr^.memberName). As a result, I pronounce -> as hat-dot (usually not aloud, but I have done so on occasion and confused the heck out of the person I was working with). -- StefanVorkoetter

It seems to me this is just a variation on HungarianNotation...

I tend to use a variation on this convention, but my intent is to increase readability. It is just a by product that scoping information may be inferred from the name. It also helps eliminate naming conflicts between class variables and parameters, primarily in constructors. English uses prepositions and possesives and including them in your variable names allows your code to read more like standard English and less like pidgen English.

I tend to use a format like "IAm..." for class booleans. This leads to lines like:

if IAmEnabled

rather than

if isEnabled

This also allows me to use "isEnabled" unamgibuously as a method name for lines like:

if theObject.isEnabled()

In general, I use first person for class variables, i.e. my.., IAm..., IHaveBeen.., etc. I use "the..." for almost all other variables, with the exception of using "a..." or "an..." for items in a collection, array, list, or whatever. The precise rules for when to use which one are not really that important, but trying to make code read like grammatic English is, I feel, important.

I HaveThisPattern. I'll take it to other types of accessors - flagIsSet(), deviceIsReady(), etc. I like the flow in conditionals.

I prefer using first person (my, Iam etc) to third person (Its...). It makes more sense to use my when referring to things private to the object. Using 'Its' make one wonder what it is. It's generally a frog or a worm.

In VisualBasic, it fits in with the Me keyword and is less surprising to people who have used the m.. or m_.. scope specifiers before.

Use Becomes rather than Set

I am currently experimenting with using the verb "Becomes" rather than "Set" in my code and was curious whether others might find this appealing. For example, instead of

myName.Set("First", "Middle", "Last");

try

myName.Becomes("First", "Middle", "Last");

After using this for a while, it seems that "Becomes" follows a subject, verb, object pattern while "Set" appears to violate it. Use of "Set" had become automatic for me and "Becomes" looked strange (for all of 5 minutes!) at first, but I now feel it is much clearer.

[An aside, as I am typing this in, I wondered if "Becomes" might also be appropriate for nameing class factories. I haven't tried this yet, so I will just wait to see how it looks in real code.]

I'm interested in hearing others reaction concerning this. I personally like it, but was wondering whether it would be too jarring for an uninitiated reader.

-- WayneMack

My first reaction is "yuck." (Yes, it is jarring.) It seems more of a description of what happens than a command or a description of what is returned (as most method/function names I've seen are). Also, your myName.Set(...) starting point seems strange; most "set" methods are named as "setSubpart".

How about setTo()? I often use names like addTo() and removeFrom() and so setTo() would fit right in.

it.puts(theLotion, itsSkin)

''How about using the Becomes pattern for objects that transition to another state instead of just changing their inherent state of attributes or properts like in

Order.becomes( Invoice )

or something like that?

And, how is your progress with the 'becomes' pattern as a whole?''