No Open Blockers

// why can't I just pass in a dictionary? sigh, there are
// times where python would make this SOOOO much easier.

To give this some context, this was seen above a manual population of attributes in a bean from a map.

I don’t really have any witty comment on this one. There are definitely times where one language would be nicer than another, so I’m in no way saying the comment is incorrect in any way. It just usually makes me laugh to find conversational comments like this, as if you could actually hear the developer sigh when typing out the wordy bean copying.

Just came across the following:

sa.setRemainingTries(new Long(10)); // hmm 10?

Not sure what the issue is with using 10 here, but for some reason it invoked the image of The Thinker.

The Spacewalk team doesn’t seem fond of the @author tag on its Java classes. I’ve heard the mentality before… “No one owns the code”… “Everyone should feel able to change it”… “You can find it out who wrote it from the source control system”… and so on.

The last rationale is especially funny to me, since on both projects where this argument was made, the code was moved to a new repository at one point and all history before that date was lost, including the original author.

I personally find the @author tag useful in finding out who to ask about a particular class. Thankfully, the Spacwalk team is pretty good about remembering who is an expert on what and I’ve never had an issue. So despite my objections, I’m fine with not using @author tags.

Then I come across this nugget in our codebase…

// /me wonders if this shouldn't be part of the query.

The /me is actually the way to emote in IRC. It is basically used to indicate you’re “doing” something rather than saying something as in a normal chat. So syntactically, I’m not confused by why the comment is phrased that way.

What I did find myself asking, out loud no less, was who the hell “me” is in this particular case.

I’m a huge fan of these sorts of inline comments as I’ve alluded to before. But one thing I forgot to mention was that I often throw my name or ID after the comment for comments that are expressing a concern or a personal belief. That way, if the code comes under review, you can ask the commenter their mentality or if the issue still applies.

Perhaps even more important is the date the comment was made. With as rapidly as things change in most projects, it’s not a surprise that a thought or comment that used to apply no longer applies. Scoping the comment to a particular time frame helps whoever stumbles upon it realize it may not still apply. It can save the next dev a lot of time wondering why a comment is saying to add something that may no longer exist.

Or, perhaps using /me is just meant as a brainwashing technique. I’m going to add a comment /me buys Professor Jay a beer to my next commit to see if it really works. And if it does, I’m enrolling my wife in my class next semester and teaching her to be a programmer.

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.