What naming guidelines do you follow?

Question

I am a huge fan of .NET Framework 1.1 Naming Guidelines available here.
Also I prefer to code using hungarian notation from Charles Simonyi.

What about you? Which naming guidelines do you follow in which programming language?

Answer 1

You should follow the lexical conventions of the file, subsystem, project, and language you're working in, in roughly that order of precedence. This will include things like the use of CamelCase versus underscores, conventional use of prefixes/suffixes, Hungarian notation (either Simonyi's original intent or the broken Systems Hungarian or neither), and so on and so on.

Once you're past the above (and that's what most people argue about), naming guidelines really boil down to effective communication: how do you make your code readable. Here are some thoughts that I have come to believe over the years.

• Choose names that are understandable when read out loud. This means they should largely follow the phrase order of the (natural) language the team writing the software. (Many of the later suggestions in fact are special cases of this one.) For example, given an object type "foo", the function name allocate_foo is better than foo_allocate because the former is the more natural English phrase.

• Name boolean variables, members, or functions in the postive sense. For example, prefer done to notFinished, empty to notFull, etc. The latter choices will lead to much more complicated expressions in conditional statements.

• Name functions that test some condition in the form of a question: isDone, or hasSomeInterestingProperty, etc.

• Name accessors with noun phrases, with adjectives as necessary. radius or backgroundColor and so on, and avoid useless prefixes on these like get or find.

• Name update operations with verb phrases. So, sort or insert or insertAfter and so on.

• Avoid vague names like handleFoo, except perhaps for things like state machine event handlers where there isn't really much else to say.

• Avoid names that expose implementation internals. Don't write findThingOnSomeQueue if the reader has to look inside the function to see what a SomeQueue is, just say findThing.

One suggestion that is often in tension with those above, and yet I also believe is quite important: Don't be (too) verbose. Good notation is concise notation, and names are a form of notation.

• Do use abbrevations for key concepts (whether in the user domain or in the implementation domain) but use them consistently.

• Do use short local variable names, especially for conventional uses such as loop indices or iterators. Otherwise, local names need to be longer as the function gets longer. (If your local variable names start to get long, your function is too big.)

I suspect that this last set of thoughts is where I most differ from current conventional wisdom.

Finally, I would highly recommend reading Clean Code by Robert C. Martin. It's probably the best book I've ever read on the general issues of code and design tidiness (including naming conventions) at the level of the function, file, and subsystem.

Answer 2

There needs to be a clear distinction between Hungarian notation as originally intended by Charles Simonyi and Systems Hungarian. Thanks to @Inaimathi for pointing to this article joelonsoftware.com/articles/Wrong.html. I admit that I was one of those who fell victim to this misunderstanding.

I don't think Systems Hungarian notation adds much value nowadays, when embedding data-type information in variable names. Linus Torvalds and Bjarne Stroustrup said it best:

Linus Torvalds:

Encoding the type of a function into the name (so-called Hungarian notation) is brain damaged—the compiler knows the types anyway and can check those, and it only confuses the programmerthe programmer

Bjarne Stroustrup:

No I don't recommend 'Hungarian'. I regard 'Hungarian' (embedding an abbreviated version > of a type in a variable name) a technique that can be useful in untyped languages, but is > completely unsuitable for a language that supports generic programming and object- oriented programming—both of which emphasize selection of operations based on the type an > arguments (known to the language or to the run-time support). In this case, 'building the > type of an object into names' simply complicates and minimizes abstraction.

I can see Hungarian notation being very valuable in UI programming where it is benefitial to know whether somethign is a text field or a label. For example, I usually do this: lblCustomerName (label preceding the text field), txtCustomerName (actual text field).

Also, whatever convention you chose, make sure the name is descriptive and does not need a comment line above variable declaration. It doesn't cost us anything to make a descriptive variable, method, or class name. In the end, the code will be more readable, which is important. Programmers spend more time reading code than writing it.

On a more technical side of things, below are some of the guidelines that I follow, which use Hungarian notation (I'm a .NET developer):

• I use Camel casing.
• 'm_' prefix for class variables
• '_' prefix for method parameter declarations
• 'I' prefix for interface names
• 'Base' postfix for base classes

Answer 3

In Elisp/Scheme/Common Lisp, I follow the naming conventions implicitly set out in Practical Common Lisp with a few changes, influenced by PLT Racket coding standards. All lower case, sub-words delimited by -, global variables wrapped by *, predicates end in ? and functions with side-effects end in !. Finally, functions that convert an input to an output get named with a -> to denote that.

For example (these aren't necessarily GOOD function names, I'm just using them to demonstrate the above standards)

sort           ;a functional sort (I expect it to return a new list)
merge-sort     ;a function with a longer name
*colors-list*  ;a global variable
starts-with?   ;a predicate (I would expect it to return NIL or the match)
sort!          ;a destructive sort (I expect it to return t or NIL and modify its inputs)
rgb->hsb       ;a function that takes an RGB color and returns an HSB color

These are all composeable, of course, so I could name a function hsb->rgb! (and I would expect that one to return t or NIL and modify the color I passed it from HSB to RGB representation). You can tell a surprising amount about what's going on in a given piece of code by paying attention to the naming conventions.

In other languages (which tend not to use prefix notation), I just stick to the standard camel-caps naming, but I do name any predicate functions with a trailing _p.

Answer 4

Following the style of the standard library for that language leads to nice-looking code. If you're in a language that does object.SomeMethod() or object.someMethod() or object.some_method() in its standard library and you follow that convention it will at least look professional.

Ultimately they're just identifiers that some compiled languages throw away anyway, so don't spend too much time deciding among someMethod, SomeMethod or some_method.

Answer 5

First: use whatever case convention is generally accepted for the language of choice, and

Second: the really important one, name classes, attributes and methods so you don´t need to write comments explaining them.

Answer 6

A better question would be, what popular languages don't have clear style guides from authoritative sources?

I checked the google and found guides for Java, C#, ruby, python, php and c/c++ in less than a minute. Within php, there are pear and drupal guidelines.

I'm convinced that much of the debate on coding styles is about the desire of some programmers to have some say on what their teammates do.

Answer 7

I use whatever ReSharper tells me to.

Answer 8

I tend to think people over complicate naming conventions. My rule is simple.

A variables name should convey the data it stores with emphasis on human readability.

That is my only rule and it has served me well over the years.

Answer 9

I follow whatever naming guidelines are published (or accepted) for the language I'm using:

In C# I use PascalCase for classes, methods, constants and enums, camelCase for variables, and _camelCase for private fields. I do not use Hungarian Notation. I use descriptive names.

In Java or PHP I would use PascalCase for classes, ALL_CAPS for constants, and camelCase for pretty much everything else.

In Ruby or Python I would use underscore_separated for variables and methods, ALL_CAPS for constants, and PascalCase for classes.

Answer 10

I work in C# and use CodeAnalysis (FxCop) and SourceAnalysis (StyleCop) to provide guidance for naming styles.

Answer 11

I think that Code Complete is a very good general book in naming stuff. It is also important that you take into consideration what language you are using.