Monday, July 31, 2006

My first BASIC compiler

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.



Picture of compiler advertisement

I started my programming "career" on a
Dragon 32
microcomputer in 6th grade. It had 32K of RAM, although once you turned the computer on it would launch a Microsoft BASIC interpreter which left 24K for your own programs. I spent countless hours on that computer in 1984, 85 and 86, writing a lot of BASIC code.



It's fun to have looped around in my career and to suddenly be working with BASIC again - in the Semplice project. If you missed it, my coworker Herbert was interviewed on the Java Posse. In addition to talking about supporting BASIC on the Java platform, he talks about supporting other VM languages in general. It's a good, meaty technical talk.



Anyway, back to BASICs. I have moved recently, and as part of the large cleanup, I had to decide what to keep. I found a stack of old computer magazines that I had held onto. These were British computer magazines I subscribed to - and were largely responsible for teaching me English. Understanding the articles in those magazines were a lot more inspiring than the stories we were encouraged to read in English class!



I realized I can't drag these magazines with me forever, so I decided to thumb through them one last time before throwing them in the recycling bin. And in one of the magazines I noticed a part of a page had been cut out. Major flashback! This was the advertisement for the first piece of software I ever purchased! The missing piece was the order form I had cut out and mailed in. And what was this product? A BASIC compiler! (I've scanned in a portion of the ad on the right.)



Yep, I was programming BASIC, but performance was slow, and I realized (from all those computer magazines) machine code was where I wanted to be. I thought a compiler would do the trick - so I bought it. My programs did execute faster - but I didn't end up learning assembly code until I got a Commodore 128, and later a Commodore Amiga. Ah the memories. The advertisement has a picture of the tape cover (I didn't have a floppy drive until the Amiga), just the way I remember it.



Tuesday, July 25, 2006

Code Advice #11: Initialize fields using the property name

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.)



How do you initialize fields in a constructor? And how do you initialize fields in a JavaBean setter method?



Here's the, in my opinion, correct way to do it:


void setTemperature(int temperature) {
this.temperature = temperature;
}

The same scheme is used in constructors.



There are various other ways to do this. Dave Yost
argues that you should use the following pattern:


void setTemperature(int newTemperature) {
temperature = newTemperature;
}

Another coding style guide recommends that you
"consider using the prefix a or an with parameter names. This helps make the parameter distinguishable from local and instance variables":

void setTemperature(int aTemperature) {
temperature = aTemperature;
}

A third scheme I've seen quite frequently is choosing a parameter name that is an abbreviation for the property name being set:

void setTemperature(int temp) {
temperature = temp;
}

A fourth suggestion is to use underscores as suffixes
on the field names themselves:

void setTemperature(int temperature) {
temperature_ = temperature;
}



So, why do I think my way is the right way to do it, and not the other alternatives shown?
As always, the first reason is that the this.x=x pattern is the most common way to do it - and as a consequence more developers will find your code clear and pleasant to read.



However, there are logical reasons to do it this way too. The primary reason is that the signature of your method is part of its API! If this is a public method, the parameter should be included in the javadoc with a @param tag. With the first three alternatives, the parameter names are newTemperature, aTemperature and temp. I think temperature is a better parameter description. Yes, it's true that for a setter method like setTemperature, it's not that important what the parameter name is since it's obvious what it's for. But when you're dealing with a constructor, you do need to be descriptive. And newTemperature is not a proper name for an initial state. You could switch to using initial instead of new as a prefix, but in addition to being wordy you now have different schemes for constructors and setters. Having one approach to both is beneficial since it keeps things simple.



The last alternative does let you use a good parameter name - the same one that I'm proposing, temperature. However, it has another disadvantage in that it's using an underscore_ as a suffix for the field name. This to me smacks of Hungarian notation, although rather than describing the object type with a prefix it describes the symbol class with a suffix. I don't like it since it makes the code less readable, but I suppose that's a topic for a whole other discussion. In short though, most Java programmers avoid underscores in all symbols but constants (such as public static final int WATER_BOILING = 100;).



The proposed style does however have one problem. It relies on "polluting" the namespace in the constructor or setter with a parameter which hides the field name. In the following code, temperature refers to the parameter, not the field:


void setTemperature(int temperature) {
this.temperature = temperature;
}


What happens if you accidentally write the wrong parameter name - either by a typo, or by writing a similar name and not noticing that the parameter name is a different variation of the field name?

void setTemperature(int temp) {
this.temperature = temperature;
}

The above code will compile just fine. However, it is probably not what is intended. If you call this method, the temperature field will not be updated - you are simply assigning the current value of the field to itself.



Luckily, your programming tools will find these errors for you. Obviously, a tool could warn you that the temp parameter is unused, and that would clue you in. But most people do not want warnings on unused parameters, since they occur frequently in a lot of code - especially when you implement interfaces.



However, the code above has a "self assignment" - the left hand side of the assignment is identical to the right hand side. This code is obviously redundant and can be removed - but more importantly, it usually points to an error of the above form. Therefore, if you run findbugs (NetBeans plugin here), it will clue you right in to the problem:






Jackpot can find self assignments as well. The following code is
courtesy of Tom Ball and will be part of the Examples shipped with Jackpot (and hopefully be built in as well).


import org.netbeans.jackpot.query.Query;
import javax.lang.model.element.Element;
import com.sun.source.tree.AssignmentTree;

public class SelfAssignmentQuery extends Query {

public Void visitAssignment(AssignmentTree tree, Object p) {
Element lhs = model.getElement(tree.getVariable());
Element rhs = model.getElement(tree.getExpression());
if (lhs == rhs) { // Elements are unique so == is okay
addResult(getCurrentElement(), tree, "self-assignment found");
}
return super.visitAssignment(tree, p);
}
}



Armed with the right tools, the this.x=x pattern works because you get to use the "right" parameter name, and the tools will catch your mistakes.


Sunday, July 23, 2006

Hot hot hot!

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.



It's unbelievably hot where I live! 111 degrees Fahrenheit in the shade - that's 44 degrees Celsius. My thermometer said 115 F, and I can believe that since I live in a part of town that is hotter than downtown where the official temperature is taken.



This of course is not conducive to working! Unfortunately, there is nothing good on TV - and I've seen all the movies in the movie theaters that according to critics are worth seeing. Not a large percentage might I add.



At least we get cool nights in California, so I can spend the morning hours web surfing a bit until it gets unbearable.
Oliver Widder has posted a cartoon related to coding styles (a frequent topic on my blog). A number of people have expressed an interested in this, so it will probably be the topic of an upcoming Java Posse episode.



P.S. My favorite drink to consume in the heat is the Mojito. It's made with ice, mint, rum, lime, and sugar. Unlike the original recipe (google it), I actually blend all the ingredients in a blender such that you get pureed mint leaves in the drink. This gives it a stronger mint flavor - which is a good thing!






Monday, July 17, 2006

Code Advice #10: Place brackets with the declaration type, not the name

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.)



The most important code style rule is that when you modify somebody else's code, you preserve the coding style in that file. Even when it hurts. The only thing worse than an "incorrectly" styled source file is an inconsistently styled one!



One of my coworkers writes Java code in a very C-inspired way. One of the habits I have difficulty with is the bracket placement for arrays. I thought I would dedicate a blog entry to this, because it occurs in many other code bases. A quick scan revealed a couple thousand matches in the JDK source code (which, granted, is a tiny fraction of the overall codebase).



Briefly stated, the correct way (as far as I'm concerned) to place brackets in an array declaration is with the type, not with the variable name. Therefore, this is okay:


int[] scores;

and this is not:

int scores[];



Here's a real-world example, from String.java:


@Deprecated
public String(byte ascii[], int hibyte, int offset, int count) {
checkBounds(ascii, offset, count);
char value[] = new char[count];
...

As you can see, there are two violations here - both in the parameter usage, and in the declaration
of local variable "value".



Most of you will probably just nod at this and move on, since it's what you're already doing. But if there's one thing I've noticed, it's that coding style blog posts always generate controversy - and that especially those of you doing it the Other Way are reluctant to change.



So, let me spend a couple of paragraphs arguing why you should place the brackets with the type name, not the variable name. The most obvious answer is that brackets-with-type is what by far most Java developers are using, so you should simply do it to make your code consistent with the accepted practice.



However, it does have some logical reasons too.



First, let's take a look at a method declaration that returns an array - this is java.util.Arrays.copyOf:


public static int[] copyOf(int[] original, int newLength) {

Notice how the brackets appear with the type declaration. You do not have the luxury of moving them to the end of the line, or even just past the variable name:

public static int copyOf[](int[] original, int newLength) { // WRONG!



Note that if you have code like this:


int[] a, b;

Here both a and b will be integer arrays. This is different than in C
where the similar

int* a, b;

would leave only a an array, and b a scalar!



Let me anticipate the objections. I can think of two advantages for placing brackets with variable names.
First, it's your only option if you want to mix and match plain and array declarations of a type in the
same statement:


int a, b[], c, d[];

However, we can dispense with this quickly: you should not compress declarations this way. Use a separate
statement for each.



The second objection, which I have some sympathy for, is that placing brackets with variable names
is consistent with the way array instances are used:


int foo[];
...
foo[i] = -1;

However, between declaration and usage we have the initialization, and the initialization uses the
typename with brackets:

int[] foo = new int[50];
foo[i] = -1;



An easy way to find violations of this coding style is to use Checkstyle. Note that while javac will
happily compile both declaration styles, the error message from checkstyle is:


Array brackets at illegal position.

I guess that's stretching the definition of "illegal" a bit (since the
Java Language Specification defines what is legal and what is not, and both forms are allowed). However, in my opinion it is good practice to place the brackets where most Java developers place them - with the typename in declarations.


Tuesday, July 11, 2006

The Trouble With Password Entry Pads...

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.


The problem with password entry pads is this:






Gee, do you think my password has any 2's in it? How about 9's?



I've had my digital token card for nearly ten years now. Amazingly, I've never had to change the battery. Anyway, while having token cards is an important part of security,
this Slashdot story shows that even these
schemes are becoming targets for phishing scams.