No Open Blockers

It’s extremely hard to teach what “good” documentation is. I can try to make suggestions when grading projects, but writing good in-code documentation really just comes with experience. In an effort to expedite that, I try to share certain experiences I’ve come across with my class to make up for their lack of experience with long running projects.

I keep threatening various Spacewalk teammates that I will blog on things they do that were… less than ideal. For instance, I asked one developer what a particular undocumented block of code did. After 10 minutes of staring at it, he still had no idea why he did what he did.

Before I get to any of that, I’ll offer myself up as a sacrifice.

I just got a message from a coworker asking me why I made a particular change to a query. I took a look at the commit, certain that I, in all of my exquisite programming discipline, would have provided a meaningful message as to the change:

“Changed package architecture retrieval to not be a join”

Shit.

A monkey could take about 2 seconds to look at the diff between my revision and the previous and determine I changed the join. The reason this message fails is because I didn’t include why I made the change. Three months after the change, I can’t for the life of me remember what the hell inspired me to make the change, which provides no help whatsoever to the poor sap who is now working with that query.

It’s a good lesson. Good documentation doesn’t just describe what is going on; for the most part you can tell that from the code (depending on the size of the change). Rather, the intention of the code is often particularly important.

For instance, a comment that says “We need the call to flush() to dramatically speed up bulk operations” shows the importance of leaving a seemingly arbitrary call in place (this example is paraphrased, but very real from somewhere in the RHQ server-side code).

Another aspect of good documentation is to describe why something may look odd to someone reviewing the code in the future. Even a comment such as “This should be refactored in the future when we port the other pages to java” is important as it shows the following code isn’t meant to be permanent. It can save a future developer a great deal of time wondering why a particular decision was made by helping to put in context any other factors that were taken into account at the time it was made.

So now that I’ve thrown myself under the bus, I won’t feel guilty pointing out other aspects of Spacewalk that make good examples of what not to do.

UPDATE: To add insult to injury, the fix to that query was committed with a rather descriptive commit message. That’s basically spiking the ball on my lame message.

In response to my post on the word “foo”, a coworker sent me this link:

http://mindprod.com/jgloss/unmainnaming.html

Some of these are freakin hilarious, but I think my favorite is:

A naming convention from the world of C++ is the use of “m_” in front of members. This is supposed to help you tell them apart from methods, so long as you forget that “method” also starts with the letter “m”.

And to preemptively address my more sarcastic students (you know who you are), yes, I will dock points if you attempt to use any of the suggesting naming conventions.

I have no reservations in saying that my current team, the Satellite/Spacewalk team, is by far the best team I’ve ever worked on. I’ve never been part of a team with the sort of cooperation, encouragement, helpfulness, lack of ego, and flat out talent that we have.

That’s not to say all of my previous teams were bad. At Gestalt, I worked with some incredible developers and from a team perspective we had great chemistry. We were just incredibly unlucky when it came to finding reasonably competent management. My previous team, the JON/RHQ/Jopr team at JBoss, has some of the brightest developers I’ve ever worked with and I really learned a ton from them. So don’t get me wrong, it’s not that I’ve been dealt pure crap as far as teams go.

It’s just that the Spacewalk team has such a great chemistry. Generally speaking, developers tend to have very big egos, commonly manifested by claiming that any code they didn’t personally write sucks (I attribute this to them being bullied in high school so now shit-talking about programming is their only avenue of power, but that’s for another entry). Our team is actually very much the opposite. When I fire off a question in our chat room, the developers are usually pretty quick to assume ownership and place the blame on themselves. This humility often leads to them being very open to other approaches and ideas, which helps across the board from the project as a whole to the developer’s personal growth. Not to mention how draining it can be working on an abrasive team.

Encouragement and appreciation is also something that’s sorely lacking on many teams. It’s amazing how energizing a one line e-mail like “Nice job” or “Slick!” is to receive. These sorts of praise don’t just come from our boss/team lead; it’s very common for other developers to understand we’re all working towards the same goal and appreciate any steps in that direction.

This idea also manifests itself in another way on our team: karma.

As a remote team, we all sit in a number of chat rooms during the day (many of us leave ourselves logged in at night too). In our internal Red Hat chat room for the team, we have a number of bots we leave in the room as well. Some have extremely cool purposes as far as managing the QA lab (an entry for another time, but trust me, it’s friggin cool) and others sit there and hurl insults at random people in the chat room (I’m not kidding about that). One of these bots keeps track of karma.

[jdob] dgoodwin++
[redken] dgoodwin now has 167 points of karma.

What does having karma get you? Absolutely nothing. It’s not factored into our raises/bonuses, you can’t redeem it for prizes… hell, I’ve never even seen people brag about their karma points. I was never even told about it when I joined the team. After a few days in the chat room, I noticed the trend and quickly started participating.

So why am I making such a big deal about it? It’s an extremely simple, quick, lightweight thank you system. You don’t need to have a big spectacle of thanks that is only used in extremely exceptional cases. It takes more to build a team than going out to lunch to celebrate a release. The daily things, no matter how small they sound on paper, are worth a ton when it comes to team chemistry and morale.

Someone answers a question or helps you out? Give them karma. Someone made a particular cool little utility for navigating bugzilla? Karma there too. I’ve even gotten karma for taking a particularly funny shot at our competitors (I’ll leave that intentionally ambiguous).

The karma points aren’t worth anything tangible, but they do speak a bit about the developer. They show that a teammate appreciated the extra effort or time you spent making their lives easier. While I haven’t seen anyone brag about their karma points, it really does say a lot when redken spits back that someone has 200 karma points.

I question how much of this post my students will be able to appreciate, not necessarily having worked in a work team environment. If nothing else, keep it in mind when you graduate and find your way into the workforce. As trivial as the karma system might sound, never underestimate the team building nature of simple appreciation, whatever the form it takes.

“Any questions before we start the exam?”
“Does the word ‘foo’ appear on it anywhere?”

It was a valid question. Prior to teaching, I never found myself using the commonly used terms “foo”, “bar”, and “baz”. I suppose if anything, I was more inclined to use “stuff” or “blah”. Yet for some reason I’d be standing at the white board last semester searching for some dummy word to use as a variable or method name in order to concretely convey a concept and I inevitably found my way back to the common three.

The pre-exam question wasn’t the first time someone called me out on it either. Last semester a student both noted that not only had I faithfully stuck with foo, but he had adopted the practice. So with last night’s comment, I figured a little googling was in order.

One definition I consistently came across is as follows:

When ‘foo’ is used in connection with ‘bar’ it has generally traced to the WWII-era Army slang acronym FUBAR (‘Fucked Up Beyond All Repair’ or ‘Fucked Up Beyond All Recognition’), later modified to foobar. Early versions of the Jargon File interpreted this change as a post-war bowdlerization, but it it now seems more likely that FUBAR was itself a derivative of ‘foo’ perhaps influenced by German furchtbar (terrible) — ‘foobar’ may actually have been the original form.

Ok, while that confirms my assumption that it somehow related to the idea of being completely fouled up — which has a definite applicability to programming — that doesn’t really say much to why foo. Not surprisingly, wikipedia had quite a bit to say:

It is likely that the use of foo in hacker and eventually in programming context originated in MIT’s Tech Model Railroad Club (TMRC). In the complex model system there were scram switches located at numerous places around the room that could be thrown if something undesirable was about to occur, such as a train going full-bore at an obstruction. Another feature of the system was a digital clock on the dispatch board. When someone hit a scram switch the clock stopped and the display was replaced with the word “FOO”; at TMRC the scram switches are therefore called “foo switches”. Because of this an entry in the 1959 Dictionary of the TMRC Language went something like this: “FOO: The first syllable of the sacred chant phrase “foo mane padme hum.” Our first obligation is to keep the foo counters turning.

That’s a pretty solid idea right there, though it lacks the “Oh, how cool” response I was hoping for. Perhaps that’s my fault for expecting some sort of grand creativity from a bunch of hackers. I did however find the following pretty interesting:

Foo or any such word used this way is formally known as a metasyntactic variable. Eric Raymond, probably the world’s greatest authority on foo and other metasyntactic variables, also lists qux, waldo, fred, xyzzy, and thud among others that are occasionally used. Although foo is the canonical metasyntactic variable, Raymond notes that cultures outside the United States have their own preferences. Fred, barney, and wombat seem common in the U.K. Toto, tata, titi, and tutu reportedly are used by the French. Blarg and wibble are used in New Zealand.

The use of a metasyntactic variable is helpful in freeing a programmer from creating a logically named variable, although the invented term may also become sufficiently popular and enter the language as a neologism. The word foo is the principal example.

If nothing else, this should give me a new pool of “metasyntactic variables” (i.e. random words) to use when I’m on the spot in front of a classroom.

Oh, and for the record, all three of “foo”, “bar”, and “baz” appeared on the exam.

To my students who don’t know what Linux is, there are two lessons in this picture:

• Tux, the penguin, is the mascot for Linux. He’s not normally in a diaper, this is just a child’s shirt version.
• My daughter is cooler than you.

I have reached a new level of laziness that I never thought possible.

As I write this, I’m sitting in my family room grading my latest project. I’m not the type to listen to music when I do stuff, rather I’m more of the type to throw on a movie I’ve seen a thousand times as background noise. I had just finished one through the XBox Netflix streaming, so I hopped on netflix.com to find something new to watch.

After poking around for a bit, I decided to throw on Matrix Reloaded. One click to add it to my instant watch queue. About 30 seconds later, my XBox beeped and I looked up to see it sitting in my queue menu. I pressed the play button on the controller and no more than 10 seconds later, it was streaming to my TV in full HD glory.

That is some seriously cool technology right there. To my students who don’t yet know what it takes for a packet to actually make it to its destination, realize it’s a freakin’ miracle that we can send a simple e-mail, much less stream gigabytes of data without pausing every 3 seconds.There’s just one problem with this whole scenario.

I already own Matrix Reloaded on DVD.

It’s in my house. I can see the door to the closet in which we keep the DVDs from where I’m sitting. I consciously decided that clicking a few buttons far outweighed my lack of desire to stand up and walk 10 feet to get the DVD and put it on.

Now if I could just figure out a way to not have to get up to go to the bathroom…

Although I can’t remember where, I once heard the sentiment Code is Poetry. I’ve always looked at coding as an art form and there is a definite distinction between clean and ugly code.

That’s not what this post is about. This post is about me being a smart ass.

The following e-mail came in on the Spacewalk mailing list this morning.

Folks have been doing pretty good with using the proper commit message
format. I applaud you for that. But, yes there is a bug, can we try
and use more descriptive commit messages? They don't have to be epic
poems, but something other than:
- a few more schema fixes
- fixed bug XXXX


Don’t get me wrong, I completely agree with it. Back on the RHQ project, there were an annoying number of commit messages that just said “Fixed JIRA 12345″. That’s irritating since you have to consult JIRA to find out what a commit was about, and if there was still an issue you couldn’t tell what the developer was at least attempting to do.

But like I said, I’m a jackass. I picked up on the “epic poems” part of that request and decided my next commit message would be done in the form of a haiku:

484285 -
Large classes are bad
Refactor and make cleaner
So can fix next bug


It was easier than I thought it would be. Next time to make things a bit trickier, I’m thinking of trying iambic pentameter. Who says code is the only place you can find poetry in a software project?