December, 2003

I was just re-reading Mr. Ed’s Get Your Filthy Tags Out Of My Javadoc, Eugene, an article he posted way back in August. Mr Ed thumps the table and demands that Javadoc be simple, terse and free of HTML tags.

In my little world, Javadoc is what you look up when you don’t have access to the source. If you do have access to the source, you go and look at whatever class or method you are interested in and – hey presto – you have both Javadoc comments _and _the source. So I only ever seem to look up Javadoc for source-free¹, third-party libraries.

But different people work in different ways, and some of my coworkers rely on Javadoc to understand the system they are building, even while it is being built. That is why I am thorough about putting Javadoc on all the code, and insist that others do likewise.

The one problem with my Javadoc is that I rarely, if ever, generate the HTML, meaning the finished result could be full of bad formatting and stupid errors (is it @return or @returns?) and I wouldn’t know.

So here is my Christmas Wish for Java. I would like some serious Javadoc support from my IDE. I’m thinking WYSYWIG, in-line Javadoc editting. That should make most formatting problems – like putting in paragraph tags – go away, and the rest bleeding obvious. Syntax checking should also be extended into the Javadoc comment to catch errors such as missing Javadoc or @param tags that don’t match the argument list.

The integration can’t be too far away – there are plenty of syntax checkers, and also some Javadoc editors already out there.

¹ “source-free” being the opposite of “free-source”.

My latest assignment, a terminal based, C++ application, is a pleasant change from the web based, Java applications that I had been working on for the last year. Even with Java’s advantages over C++, I suspect it would take longer to build a web version of this application than a terminal version.

A typical web application consists of a bunch of little programs, all doing this:

1. Work out what the user wants to do.
2. Work out if the user’s session is in the correct state to do that.
3. Validate the input.
4. Peform the action.
5. Save session state so you know where you are for the next request.
6. Generate the HTML response.
7. Return to the server.

Early on, the Java people standardised the interface to these little programs and called them servlets.

In constrast, a terminal application has a bunch of subroutines that all look like this:

1. Display a screen.
2. Get an action from the user.
3. Perform the action.

Not nearly as complex. And because the code is not stopping and starting with each interaction, there are no session state bugs, fewer security issues, and it really is about half the code.

Aaron Watters puts it succinctly:

Unrolling the application at each point where you need to wait simply turns the code inside out…

Of course, the reason why we write our applications inside-out is that it scales much better than if we don’t. What if there was a way to build scalable applications “inside-in and outside-out”? Jeremy Hylton points to a number of papers and projects addressing this problem.

I signed up for the Gowings Club. It gives me a small discount in exchange for receiving the odd bit of email advertising. They sent me this today:

Subject: Champions of the World

Dear Gowings Club Member

On Friday last week we sent you an email with a “Gowings Club Member Only” special offer on Wallabies jerseys.

This special promotion was sponsored by a company trading as “Champions of the World” and contained their logo at the top of the page.

“Champions of the World” is currently trading from the first floor within the Gowings building on the corner of George and Market Street Sydney.

While we are very proud of the Wallabies we were not suggesting in any way that the Wallabies were the world champions or trying to detract from England’s victory at the recent Rugby World Cup final.

Thank you
for and on behalf of
The Gowings Club

And, in case you were wondering, here is relevant part of the original email…

Special Offer
for
Gowings Club Members Only

Wallabies Jersey
Was $139.95 Now reduced to $99.00

Gowings Club Members can take another $10.00 off
Only pay $89.00

… and so forth

Is this a genuine response to complaints by stupid people? Are there English rugger supporters out there with such a big chip on their shoulder that they believe that:

a. the original email somehow implies that the Wallabies are “Champions of The World”, ¹

b. a department store would attempt communist-style, historical revisionism on the Rugby World Cup, ²

c. this department store would attempt such revisionism less than three weeks after the undeniably exciting and memorable grand final, in the country that the final was played, while selling a product only likely to be bought by those who had actually watched the game, ³ and

d. those receiving the email might actually be deceived.⁴

And another thing: What were Gowings thinking when they sent that apology?

¹ If anything, it most likely implies that Gowings Club Members are “Champions of the World.” It second most likely implies that Wallabies Jerseys are “Champions of the World.” The only way you could make it say that Wallabies are champions of the world is by a careful and purposeful mis-reading.

² By and large, Australians care about rugby more than religion. They wouldn’t lie about something this important.

³ A corporation stupid enough to attempt this would have shot themselves in the corporate foot long ago. The fact that Gowings are still in business speaks for itself.

⁴ Whereas the only people I can imagine misreading the email like this already know that England won.

For the last month or so, I’ve been ‘doing’ C++. The project is based on NCurses, an open source implementation of the curses character terminal library.

After working with Java and Python for so long, NCurses seems, well… horrible. If you make a programming mistake, the typical NCurses reaction is to print either “form library error”, or maybe even “menu library error”, crash your application, and leave the terminal in a strange mode, requiring you to type in a secret (by dint of character echo being turned off) incantation and press CTRL-J before proceeding.

Anyway, just before lunch yesterday, my application stopped updating the position of the terminal’s blinking cursor. You would think that a product named Curses could keep track of a cursor wouldn’t you?

Closer inspection revealed that all the keys worked properly, TAB cycled through fields as expected, and the Curses getyx() call reported that the cursor was in the correct place. Only the cursor wasn’t in the correct place at all; it was stuck half way down the screen, and it was blinking at me.

I spent the next 14 working hours debugging.

It came down to a function named getch(), which gets characters. I thought I was calling the standard ‘C’ library getch(), but it turns out I was calling a C++ member function named getch(). During a refactoring, I moved the getch() call from one class to another, and all of a sudden it was now referring to a global function named getch(). This global function worked fine, except for entirely screwing up cursor positioning.

In fact, the NCurses header files declare fifteen different getch()s. Some are global functions, some are member functions, and some are macros. I still can’t pin down exactly which one I was calling, but it was a one line fix.

And the moral is, “When you need to get a char, use the Curses getch(), without the cursed gotcha.”

The newly released LUFS-Python is a Python interface to the Linux Usermode File System, and it looks pretty neat.

Since I hadn’t even heard of LUFS, before, I went and installed¹ it tonight, then used the provided ssh file system to connect to my web host. It all just works. I can edit my website’s files like they were on a local disk, though saves are a little slow.

Simon Willison and his readers have some neat ideas about what you could do with LUFS-Python, assuming the combination of LUFS and Python is stable enough.

Myself, I’d like to build a filesystem interface for CVS, mostly as an academic exercise.

¹ Thanks to the Power Of Gentoo Linux, ‘installed’ is really too grand a word for the process. I simply typed ‘emerge -s lufs’ to search for a lufs ebuild – version 0.9.5 was available, and then ‘emerge lufs’ to download and compile it. A few minutes later, LUFS was up an running. Even less fuss than a typical Windows, “Next, Next, I Agree, Next, Next, Next” install.

Tedious Soporific points to a quote from an Economist article on Brad DeLong’s blog. The article gives President Bush a hard time for taking credit when perhaps credit is not due. I don’t think this is really fair – politicians constantly get the blame even when blame is obviously not due, so why shouldn’t they take credit when it might conceivably be due?

The article has more harsh words for President Bush:

Gary Clyde Hufbauer of the Institute for International Economics (IIE), a Washington think-tank, warns against the post hoc ergo propter hoc fallacy. That won’t bother Mr Bush, who is not known for his command of Latin….

I’d like to help out President Bush and everybody else who didn’t do enough high school Latin to translate “post hoc, ergo propter hoc”. Word by word, we have:

• post* v. To send by mail.
• hoc n. Illegally distilled alcohol – moonshine, rotgut.
• ergo adv. Therefore.
• propter n. Ancient Roman cross between a helicopter and propeller driven aircraft.

“Post hoc, ergo propter hoc” therefore means:

“Send moonshine by mail therefore the moon-shines on the auto-gyro”.

I can see the logical fallacy in that.

I read “Manna” by Marshall Brain on the train into town today, and Cory Doctorow’s “0wnz0red” on the way back. Both are computer-nerd, sci-fi short stories, set in the near future.

(Minor Spoilers Ahead)

Simon Brunning pointed me to “Manna”, and I find myself in agreement with his analysis – the Manna system is plausible, but the Australia Project isn’t.

The problem with the concept of the Australia Project is that it assumes a large number of people will live in harmony and mutual respect if there is no material reason for envy, totally free communication and a commitment to shared principles. Bah! I submit a selection of communications between various open source luminaries and hangers-on as counter-examples.

That said, it was still a bit freaky looking out the window when I was just starting chapter 7. The train was near the Strathfield signal box, where the trackside is over-grown and rusted locos sit on the siding, looking like they will never move again. I found myself wondering what it would all become when the Australia Project was through with it.

“0wnz0red” I found via link from Ben Zanin, in a comment on Charles’ blog. “0wnz0red” is interesting, if it is a little dark, and everybody loves a happy ending.

It was good to read these stories back to back, since they deal with similar social and scientific themes, are written by authors with similar technical backgrounds but then go on to reach quite different conclusions.

Overall, “0wnz0red” is more satisfying as a story, but “Manna” made me think harder.

Charles’ recent blog entry on test decorators put in mind of a presentation I attended in a previous life.

The authors of the presentation had been writing code that managed a 99.999% available environments. IIRC, their software didn’t have to be 99.999% available itself, but it did have to be responsive and it could not destabilise any other software running nearby.

To help them achieve their goals, they wrote decorators for their unit tests that measured memory usage and execution times, then logged the results in a file.

The authors then graphed and compared the logged results between runs, allowing them to watch for changes that indicate a design defect in their algorithms or a bug in their memory management. In this way, they headed off several issues that were not obvious otherwise.

Two questions spring to mind:

A. How hard is this to do? With caching, pooling and all the really tricky stuff that goes on inside a J2EE server, pinning down memory usage in an EJB app would be difficult. However, recording the elapsed time for each unit test would be simple and useful. The big ‘trick’ would be to have a test decorator write out a line to a log file containing, say, the test name, date and time, user name and elapsed time. Maybe Charles would lend me his five line Ruby script for decorating Java tests, and a few moments work in Excel or StarCalc would make pretty graphs out of the log file. Easy-peasy.

B. If it’s that simple, why aren’t I doing this all the time? Ummmm… gee… I guess I just never thought of it before. It would be good to be paying more attention to performance from the get-go, and, since it looks to be almost free, I’ll have to start doing it.

Tedious Soporific has a blog. He sure kept that quiet.

Blogrolled.

After years of being a weedy bean-pole, my eight year old son, Mitchell, is finally starting to put on a little muscle.

When I told him how pleased I was to see him growing up, he grinned broadly, and pointed to his stomach. “I’m also getting a two-pack,” he said.

So long as he finds the other four before he wants to impress the girls, I suppose that’s OK.

When I worked at the Sydney R&D office of a large, American technology company—way back in 2001—we had small ceramic pig that was awarded each Friday afternoon for the week’s most egregiously stupid act. There was plenty of material to work with, and it usually came down to a vote between three or four excellent candidates.

Pig Story One

I won The Pig once. We were developing a product that notified users of important events in a call centre. A feature was the ability to send SMS messages via a web gateway, and we had purchased 1000 message credits for testing and demonstration purposes. It was all fun and games until a certain Friday when I accidently left a test system up, generating events which our little program dutifully turned into SMS messages.

Unfortunately, I had just asked everyone to be careful with our 1000 message credits, as it had been difficult to get the expenditure approved.

Fortunately, we had just implemented a throttling mechanism, so only 300 or so SMS were actually sent to the test phone.

Unfortunately, the test phone had been turned off for the weekend, so all the SMSes were queued up in the phone company’s systems, ready to be delivered the moment it was turned on.

Fortunately, this was not really an issue because the phone company only stores SMS messages for a few days, so all we had to do was leave the phone off until Wednesday.

Unfortunately, an engineer had taken the phone to the U.S. as part of a big demo, scheduled for Monday morning. I was actually teleconferenced in when the engineer turned the phone on, and it beeped three times to announce the delivery of the first of the three hundred SMSes. Then it beeped three times to announce the delivery of the second of three hundred SMSes. Around SMS number five, the poor engineer admitted defeat, and turned the phone off.

Pig Story Two

To my mind, though, the most memorable pig award was made to Leah, a technical writer who was doing her best to put together a company newsletter. Leah had just finished a draft, so she fired off a quick email asking her new manager, Russell, to review it.

Russell wrote back within ten minutes. The font was all wrong (they were the company mandated fonts.) The colours were not right (Leah had spent hours on them.) The text was shoddy (a deadly insult.) In short, Leah was furious. She stewed for a little, then took her complaint to her team leader, Jenny. Jenny confronted Russell.

And Russell professed utter ignorance.

After some investigaton, it turned out that Leah had typed “Russell” as the “to:” address of the email. MS Outlook, helpful as ever, had chosen to send the email, not to her manager Russell, but to her friend Russell in Western Australia, on the other side of the country. Friend Russell hadn’t even received the draft newsletter attachment, but, for whatever reason, felt compelled to type out a quick, witty, and critical reply.

Leah must have blushed for a day.

Pig Story Three

I had completely forgotten about the Pig until, out of the blue, an email arrived from Kevin Chan announcing the sale by auction of the only-slightly abused figurine.

Here is the link to the page on eBay.. Auction closes December 8. Not your usual eBay treasure. It made me smile.

Classic Kevin Chan, right down to the $10.00 opening bid.

Know another Pig story or ten? I’d love to be reminded of ones I may have already heard, or hear others from before or after my time. Please mail me or leave a comment.

I met Paul Croxen on my first night at the NSW Institute of Technology, way back in 1987. There were four of us: Paul and David had cadetships with the NSW TAB, while Carolyn and I had a cadetships with St. George Building Society. Our cadetships combined full-time, on-the-job training with part-time study for two years, followed by two more years of full-time study. We called ourselves “space cadets” and have been friends ever since—seventeen years.

Sadly, Paul died last Wednesday.

Here are some things I remember about Paul:

• Paul was a country boy. When I first met him, he spoke with the casual, slow-paced delivery that is typical of Northern NSW. Over the years, took on more of a city accent, but whenever he reminisced about growing up Taree, his voice would slow to a drawl.

• Paul taught me good Aussie expressions such as “Flat out like a lizard drinking,” and “Off like a bucket of prawns in the sun.” Even in fourth year, he could still catch me off-guard with an expresson I hadn’t heard before.

• Paul introduced me to The Proclaimers and Bon Jovi.

• Paul had a real 1200/75 baud modem on his Commodore-64. I was impressed. The modem was connected by a funny little PCB sticking out the back of the C-64’s expansion slot. One night we got a list of BBSes in Sydney and dialed into a few. Sometime around 12:00am, we were having trouble connecting on one particular number, so I dialed it on the phone and got an earful from some poor bloke I had woken. While I stammered through an apology, Paul was urgently dispensing the most sensible advice, “Hang up! Hang up!”.

• Paul managed to be brainy, hard-working and likeable all at the same time. Us four space cadets did our group-assignments together, and, unlike myself, Paul was a perfect team member. IIRC, Paul graduated third in our year.

• Paul liked to stay abreast of current affairs and to do the Right Thing. When the issue of plastic bags killing marine life was first raised in the media, Paul immediately set about buying less plastic, using fewer shopping bags and even chopping up the troublesome plastic rings that come on 2 litre milk bottle caps.

• Paul met Kylie. One Monday, I asked Paul how his weekend was. He said, “Oh, good, I went to a party,” but his flat mate interjected with the news that Paul had met a girl, and spent several hours alone in the bedroom with her. “We were just talking!,” Paul protested. After a little ribbing he admitted that there were, perhaps, hands on knees. It was all so very sweet.

• Paul was the first among the four of us to have children. He did a really good job of it, too: twin girls! Later came a boy, and he cherished all three of his children.