More About Examples

I've been meaning to post some comments Joe left me:

Blaine,

I don't read your blog as often as I'd like, but whenever I do it gets me thinking.

I cut my teeth on the first edition of "Java in a Nutshell" and agree many of the code examples are horrible. For some unfathomable reason, most Java books make little or no attempt to teach OO concepts, choosing instead to focus on syntax and the API.

The problem with correcting code is that your corrections are open for correction :) In fixing the "baby sins" you've created, IMHO, a more egregious one. public methods with filname parameters is generally a Bad Idea as it allows a careless coder to corrupt any file of his choosing.

Well, but, I was trying to show a simple example. Wait a minute. I'm in the very quicksand that I complained about. Ouch. You are so right. I would generally have file access behind some kind of broker and then had the operations split out. Darn it! Maybe I should keep my mouth shut because it's hard to come up with succint yet correct examples.

You've also created some minor baby sins (embryo sins?) yourself. I believe redundancy does not necessarily lead to clarity. The repetitive "InCents" while well intended, gets downright annoying. I only need to be told once that we're dealing in cents. When you switch to another unit measure, let me know, otherwise it should be safe to assume nothing has changed. Make cents, er, sense? By renaming the method to addCentsToPurse, it pretty clear that cents is the order of the day.

Well, I usually have an object to represent money. Wait a minute. I'm down my rat hole again. DARN IT! You are exactly right. The "InCents" does get annoying. I usually put them in when I'm dealing with legacy code that deals in primitive. I don't like dealing with primitive types at all. Again, it's hard to come up with good examples. I should have done the right thing. I wrote the counter example in haste and committed sins in my rush.

Your constant and variable names are a little too "techie." I've lately come to understand that if code can be read by a non-coder, coders will be able to read it all the faster. seek(TOTAL_AMOUNT) is less technically accurate than seek(RECORD_POSITION) but it more clearly indicates what we expect to find at that location.

Another great suggestion and one that I fight with constantly. I do try to come up with good variable names, but I do fall into the techie trap a lot. Thank you for giving me more ammo to fight this battle in my head.

So, here's my version (hoping the format looks ok):

private static final String PURSE = "blah";
private static final String READ_AND_WRITE = "rw";
private static final int TOTAL_AMOUNT = 100;

public void addCentsToPurse(int cents) throws IOException {
RandomAccessFile purse = new RandomAccessFile(PURSE, READ_AND_WRITE);
try {
purse.seek(TOTAL_AMOUNT);
int centsInPurse = purse.readInt();
int total = centsInPurse + cents;
purse.seek(TOTAL_AMOUNT);
purse.writeInt(total);
} finally {
purse.close();
}
}

As a final note, I'm always tempted to combine multiple lines, as in:

purse.writeInt(centsInPurse + cents);

While this is a trivial example, it does help with debugging to use a new variable and multiple lines.

Jeff

WOW. Excellent code. I love these kinds of comments. It should a lot of faults in my code and I learned a lot. Great stuff. And we got a better example out of it to boot. Thanks, Jeff...You ROCK! I will work harder to make my code the best it can be and encourage everyone else to do the same thing.