WARNING: This blog entry was imported from my old blog on blogs.sun.com (which used different blogging software), so formatting and links may not be correct.
(See intro for a background and caveats on these coding advice blog entries.)
I came across a JavaWorld coding-advice article the other day. While the thread which led me there referenced the second point of the article, I couldn't get past the first one where the author argues that
...a reader needs to know which items are local variables, which are fields, and which are method arguments. [...] It's likely best to use a simple naming convention to distinguish between these three cases.
I couldn't disagree more!
His key argument seems to be that when you are reading code, it's important to know whether something is a field since when you read a method, you might suddenly see a reference to something you haven't seen before. To make his point he shows this graphic:
His improved version is here:
I have a couple of problems with this.
First of all, why encode this information in the symbol name when IDEs will show this information automatically? NetBeans will show fields in greens, and statics in italics - and it will always be right, whereas the code might lie. Just like comments can get out of sync with reality, you could inline a field without remembering to change its name (especially if another developer did it without realizing the meaning of the variable prefix). Or if you get in the habit of seeing an "f" prefix as meaning field, what about local variables that legitimately should start with an f, such as "focus" ? Sure, the second variable should be capitalized, but what about typographically similar symbols like lowercase l and uppercase I?
Here's how the same function looks in NetBeans:
In addition to showing us the fields in clear green, the IDE also pointed out that this method is overriding another method (I hovered over the overrides glyph in the editor margin). The yellow line is warning us that this override doesn't have an @Override explicit annotation on it.
Information about overrides is just as important as whether an identifier is a field.
Highlighting fields in green isn't specific to Java... We do this for many other languages - see some screenshots of
Ruby,
PHP,
Groovy, etc.
Here's a snippet of JavaScript - notice how we have a reference to a global variable in there shown in green:
The key point here is that you shouldn't write your code to target reading code in black and white on paper. You shouldn't print out your code at all! Reading code with an IDE lets you easily check any condition you encounter (and just like in a browser there is a little go-back icon in the editor toolbar which maintains a visit stack so you can easily pursue multiple ctrl-clicks to track something down and then easily go back).
There are some other conventions left over from the days of code written on tiny terminals and printed out on paper for review - such as the "maximum 72 characters per line" limit. There's no reason for that when using modern tools. If the code is more readable unwrapped at 100 characters, leave it that way rather than introduce arbitrary breaks in the middle. (Having said that, don't take this as an endorsement to write deeply nested methods, that's a sign of poorly thought out design.)
My second objection to the article is that it is not clear to me that knowing whether something is a field or not is the critical piece of information you need. I think the following questions are probably more important:
- What is the meaning of the variable, and what is the intended use?
- Can it be null? Can it be negative?
- What is its type?
- Where else is it referenced?
And so on. Just prepending an "f" on a field
reduces readability in order to avoid a simple lookup, when I believe you in general
need to know more context anyway.
And again, a tool can help you here. In NetBeans, hold down the Ctrl key (Command on the Mac) and hover over a symbol and you get help like
this:
(As a side note: I heard that at a Scala talk in JavaOne, Bill Venners was showing NetBeans through most of his talk, but he switched
to Eclipse to show one feature: Pointing at symbols show the actual inferred types of scala identifiers. Scala is as you know a statically
typed language, but uses a lot of type inference so the types aren't obvious from looking at the source. That's a very useful feature,
and I thought I'd point out that NetBeans has this feature too -- using the exact same mechanism as the above; just hold the Cmd/Ctrl key
and hover over a symbol, and you will see its type.)
Finally, the article makes a point that you probably want to distinguish parameters as well. I agree with that, but again not by changing
the name of the parameters, but through color identification. In Ruby, JavaScript, Python etc. we do that automatically in NetBeans - parameters are orange by default. For Java, it's not enabled by default (at one point it was, but somebody determined that the source code just looked too colorful, so the default color scheme was dialed back. I was working on Ruby at the time so my colors flew under the radar... and
all GSF-based languages such as JavaScript, Python, Scala etc. now inherit that color scheme...)
You
can turn this on for Java as well. Just open the preferences, and for Fonts and Colors choose the Java language, then customize the Parameter Use and Parameter Declaration values:
Some languages like Ruby use sigils, where fields start with @, globals with $, symbols with : and so on. I don't have a problem with that
since I don't think these are as obtrusive as -letters- in variable names.
If you are reading code on paper, or with an editor that doesn't support semantic highlighting, you are voluntarily handicapping yourself.
