All | About | AJAX | BASIC | Creator | General | Java | JavaFX | NetBeans | Personal | Posse | Ruby

20090616 Tuesday June 16, 2009

Code Advice #16: Don't Encode Symbol Type in Variable Names!

(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: 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.

(2009-06-16 14:10:26.0) Permalink Comments [5]

20080201 Friday February 01, 2008

Why Your JavaOne Submission Was Rejected

JavaOne submission acceptance letters - and rejection letters - starting going out last night. This year, I was on the review committee for one of the tracks, so I got to see the proposals as well as the reasons for rejecting many of them. I thought I'd write these up, both to explain to the many submitters what might have gone wrong, as well as to give some tips for how to improve your chances next year. I'll probably link back to this post around the time submissions for JavaOne 2009 open up later this year.

Finally, work one one strong submission rather than submitting 5-10 half-baked ones; just adding lots of abstracts does not help your odds given my points above about the low number of available slots; each submission has to be fantastic.

(2008-02-01 12:59:41.0) Permalink Comments [3]

20080105 Saturday January 05, 2008

Ruby Screenshot of the Week #26: Ruby 1.9 Changes - hashes and case statements

Ruby 1.9 has been released. It's a "development" version meaning that you wouldn't want to use it in production, but now is a good time to learn the new ways of doing things such that migrating to Ruby 2.0 will be easier.

Via Ruby Inside, I read James Edward Gray's recent blog entry detailing the work he did to update his library to 1.9 - and a number of people leaving comments are also pointing out language changes.

One such change mentioned is case/when statements not allowing colon as a separator. (I don't see this in Ruby Changes Wiki - does anyone have a source for this?). Seems like a a good candidate for a Ruby quickfix:

There are a couple of available fixes:

The first one is just replacing the colon with a then:

The second fix is instead putting the statement on a separate indented line:

Another language change I found in Sam Ruby's post is that you cannot write hashes as lists anymore. Here's a quickfix for that - first the code, this is from webrick's httpstatus class:

The quickfix is attached to the first list entry in the hash:

And previewing the fix shows the following proposed edit:

As usual, the NetBeans Ruby forums can be accessed via Nabble here and Gmane newsreaders here (other feedback channels here).

(2008-01-05 12:36:49.0) Permalink Comments [9]

20071002 Tuesday October 02, 2007

Disable Crashing...

If you're on OSX, and you've experienced NetBeans 6.0 beta crashing on you, read on...

Right before beta1, we tweaked some of the Java VM startup flags NetBeans uses. In particular, we switched to the "Concurrent Mark Sweep" (CMS) garbage collector, which has a nice performance profile for IDE usage, since collection happens mostly in parallel so you don't get noticeable pauses.

Unfortunately, it turns out that these flags cause a lot of problems on OSX. In particular, they cause frequent virtual machine crashes!

Knowing this, for beta2 we've turned off those flags when running NetBeans on OSX. But that doesn't help you if you're trying to run beta1... Luckily, it's easy to fix it yourself, since the VM parameters are specified in a text configuration file.

First, open the netbeans.conf file. On my Mac, I installed NetBeans in Applications under NetBeans, so the file is 

/Applications/NetBeans/NetBeans\ 6.0\ Beta\ 1.app/Contents/Resources/NetBeans/etc/netbeans.conf
The file contains this: 
# Options used by NetBeans launcher by default, can be overridden by explicit
# command line switches:
netbeans_default_options="-J-client -J-Xms32m -J-XX:PermSize=32m -J-XX:MaxPermSize=200m 
  -J-Dapple.laf.useScreenMenuBar=true -J-XX:+UseConcMarkSweepGC -J-XX:+CMSClassUnloadingEnabled 
  -J-XX:+CMSPermGenSweepingEnabled"
# (Note that a default -Xmx is selected for you automatically.)

# For JVMs which does not support Concurrent Mark & Sweep garbage collection
# algorithm remove "-J-XX:+UseConcMarkSweepGC -J-XX:+CMSClassUnloadingEnabled 
# -J-XX:+CMSPermGenSweepingEnabled" part of options
# (see http://wiki.netbeans.org/wiki/view/FaqGCPauses)

Remove the bold section above; in other words, remove these 3 flags: 

-J-XX:+UseConcMarkSweepGC -J-XX:+CMSClassUnloadingEnabled -J-XX:+CMSPermGenSweepingEnabled
Now when you restart the IDE should behave better.

(2007-10-02 09:09:21.0) Permalink Comments [1]

20070724 Tuesday July 24, 2007

NetBeans Ruby support interview

Roman and Gregg interviewed me in the latest episode of the NetBeans podcast.

Here are the shownotes from Roman's blog:

The episode is here, subscription is here.

(2007-07-24 12:43:19.0) Permalink Comments [3]

20040816 Monday August 16, 2004

First Post Hi. This is my first blog entry.

I work on the Sun Java Studio Creator product (formerly, and by the development team fondly) known as "Rave". (Well, when going public with it last spring we had to rename it "Project Rave" to avoid trademark issues.)

I'm responsible for the visual page designer, as well as the navigation editor.

On this page I plan to post Creator-related news and thoughts - as well as any other random things I want to say. Tune in if you're a Creator user, or if you haven't tried it yet, head over to www.sun.com/jscreator.

(2004-08-16 21:45:25.0) Permalink