Follow the Naming Conventions
- Capital Letters and Underscores
- Microsofties
- Brevity
- Dealing with It
Like this article? We recommend
Like this article? We recommend
Like this article? We recommend
No two programmers write with exactly the same style. A programmer may not even be self-consistent. I sometimes forget my own coding style, and use different styles at different times, or even on the same file, modified over time. Sometimes_I_write_like_this, and otherTimesLikeThis.
It can be troublesome to read code written in somebody else's style, but it would be even worse to try to change somebody else's code to match your own style just to make it easier on yourself. That process is slow and error-prone, and programmers down the road will have to repeat it, because your style won't match theirs, either. The best thing you can do is to learn as many styles as you can, recognize the benefits and disadvantages of each, and love (or at least live with) whatever comes to you. Recall one of the most important principles of maintenance programming: Tread lightly.
Some naming conventions have become nearly universal. Here's a frequently-seen chunk of code:
for(int i = 0; i < args.length; i++)
Programmers had better know that i in this example is a standard integer index. This goes back to FORTRAN, where you didn't even have to explicitly declare the variable because the compiler assumed that it knew what you meant based on the first letter: Any variable beginning with i, j, k, l, m, or n is automatically an integer, and anything else is real.
I've even known a few programmers who wouldn't accept that, and would instead write this code as follows:
for(int indexIntoArgs = 0; indexIntoArgs < args.length; indexIntoArgs++)
More power to them, I guess, for using a nice descriptive name, but it's too bad that such a common idiom takes up three lines instead of one.
Some programmers prefer long, descriptive names, and others prefer short, punchy ones. The former are easy to read but tedious to type. The latter can be almost completely incomprehensible.
As a maintenance programmer, your best strategy is to mimic whatever code you're maintaining, although I have to admit that on occasion I've been forced to expand an overly abbreviated name or truncate a verbose one just to be able to read the code. But I do that in my own copy, not the copy I return to version control, because the potential to have missed something crucial is just too great.
The risk is that you could miss a use somewhere. At best, the program would fail to compile, but it's not even a sure bet that the compiler would catch the error. All too often, people take shortcuts around recompiling everything, and errors like that make it into operational code, where they materialize later as ugly crashes.
In addition, a global search-and-replace has an annoying tendency to replace too much. A programmer trying to substitute indexIntoArgs for i blindly will find that bad things have happened to the while loops as they become whindexIntoArgsle loops. And a manual search-and-replace is error-prone and tedious.
Modern refactoring tools, which operate based on the syntax of the program rather than just plain text, will make this easier. In addition to recognizing whole identifiers rather than just strings of letters, they understand the scoping provided by braces. Until you have one of those, however, the search-and-replace will be painful. Even if you do have a refactoring tool, there's good reason to avoid changing naming conventions, as we'll see shortly.
Capital Letters and Underscores
Let's look at some samples pulled from the Jakarta Ant project.
Main.java:
private PrintStream out = System.out; private static void printMessage(Throwable t)
ClearCase.java:
private String m_ClearToolDir = ""; protected int run(Commandline cmd)
Wizard.java:
private JProgressBar _progress = null; public void addWizardListener(WizardListener l)
ConstantPoolEntry.java:
static public final int CONSTANT_InterfaceMethodRef = 11; public ConstantPoolEntry(int tagValue, int entries)
All of these examples declare fields in Java classes. Four files, four authors, four different naming conventions. Main.java makes no distinctions between fields, methods, and local variables. ClearCase.java tags fields with m_ (for member), while Wizard.java just uses the underscore. ConstantPoolEntry.java makes final variables all caps, similar to the #define convention in C. (#define caused me substantial grief when I was a C programmer. But that's another column.)
On the upside, all of these methods use pretty much the same convention for method names. In general, Java programmers seem to agree that BiCapitalization (separating multiple words in a filename with capital letters and no other marking) is the way to go with method and class names. I've also heard this strategy called camelCase, InterCaps, and a slew of other names. That's the standard followed pretty much universally by the Java SDK, at least the parts composed by Sun. Outside the Java SDK, things get a little hairier, as in this example from the OMG:
public abstract C:\Programs\jdk1.3.1\docs\api\org\omg\CORBA\Any.html add_named_in_arg(C:\Programs\jdk1.3.1\docs\api\java\lang\String.html name)
C programmers—and Java programmers who spent time as C programmers—tend to separate words in names with underscores instead, as in this example from the Linux scheduler:
static inline void enqueue_task(struct task_struct *p,
prio_array_t *array)
Neither of these standards is inherently better than the other, which explains why both styles persist. I rejected BiCapitalization for a long time because it was the Pascal way of doing things rather than the C way of doing things. Now I prefer BiCapitalization since it's the Java way of doing things rather than the C way. I mention this to point out that your rationale for preferring your style to everybody else's is almost certainly just as silly.