Archive for April, 2012

Before you write a patch, write an email

April 27, 2012

I often get surprise patches in my projects from people I’ve never heard from.  I’m not talking about things like fixing typos, or fixing a bug in the bug tracker.  I’m talking about new features, handed over fully-formed. Unfortunately, it’s sometimes the case that the patch doesn’t fit the project, or where the project is going.  I feel bad turning down these changes, but it’s what I have to do.

Sometimes it feels like they’re trying to do their best to make the patch a surprise, sort of like working hard to buy your mom an awesome birthday present without her knowing about it. But in the case of contributing to a project, surprise isn’t a good thing. Talking to the project first doesn’t take away from the value of what you’re trying to do. This talking up front may even turn up a better way to do what you want.

There’s nothing wrong with collaborating with others to plan work to be done. In our day-to-day jobs, when management, clients and users push us to start construction of a project before requirements are complete, it’s called WISCY, or Why Isn’t Someone Coding Yet? As programmers, it’s our job to push back against this tendency to avoid wasted work. Sometimes this means pushing back against users, and sometimes it means pushing back against ourselves.

I’m not suggesting that would-be contributors go through some sort of annoying process, filling out online forms to justify their wants.  I’m just talking about a simple email. I know that we want to get to the fun part of coding, but it makes sense to spend a few minutes to drop a quick note: “Hey, I love project Foo, and I was thinking about adding a switch to do X.”  You’re sure to get back a “Sounds great! Love to have it!” or a “No, thanks, we’ve thought about that and decided not to do that”.  Maybe you’ll find that what you’re suggesting is already done and ready for the next release. Or maybe you’ll get no reply to your email at all, which tells you your work will probably be ignored anyway.

I’m not suggesting that you shouldn’t modify code for your own purposes.  That’s part of the beauty of using open source. If you need to add a feature for yourself, go ahead. But if your goal is to contribute to the project as well as scratching your own itch, it only makes sense to start with communication.

Communication starts with understanding how the project works. The docs probably include something about the development process the project uses. While you’re at it, join the project’s mailing list and read the last few dozen messages in the archive.  I can’t tell you how many times I’ve answered a question or patch from someone when I’ve said the same thing to someone else a week earlier.

Next time you have an idea to contribute a change to an open source project, let someone know what you’re thinking first. Find out if your patch is something the project wants. Find out what the preferred process for submitting changes is. Save yourself from wasted time.

We want your collaboration! We want you your help! Just talk to us first.

What if news stories were written like resumes?

April 20, 2012

If news stories were written like the resumes I see every day, a news story about a fire might look like this:

“There was a fire on Tuesday in a building. Traffic was backed up some distance for some period of time. Costs of the damage were estimated. There may have been fatalities and injuries, or maybe not.”

Now look at your resume. Does it have bullet items like “Wrote web apps in Ruby”? That’s just about as barely informative as my hypothetical news story above. However, your resume’s job is to get you an interview by providing compelling details in your work history.

Add details! What sort of web apps? What did they do? Did they drive company revenue? How many users used them? How big were these apps?

Or maybe you have a bullet point of “provided help desk support.” How many users did you support? How many incidents per day/week? What sorts of problems? Were they geographically close, or remote? What OSes did you support? What apps? Was there sort of service level agreement you had to hit?

If you don’t provide these details, the reader is left to make her own assumptions. “Help desk support” might mean something as basically as handling two phone calls a day for basic “I can’t get the Google to work” questions. Without details you provide, that’s the picture the reader is free to infer.

When you write about your work experiences, you have a picture in your head of the history and skills you’re talking about. To you, “wrote web apps in Ruby” or “provided help desk support” brings back the memory of what that entailed. The reader doesn’t have access to your memory. That’s why you have a resume with written words. You have to spell it out, to draw that picture for her. Your details make that happen and increase the chances you’ll get an interview.

Programmers, please take five minutes to provide some data for an experiment

April 19, 2012

Whenever people talk about ack, there’s always a discussion of whether ack is faster than grep, and how much faster, and people provide data points that show “I searched this tree with find+grep in 8.3 seconds, and it took ack 11.5 seconds”. Thing is, that doesn’t take into account the amount of time it takes to type the command.

How much faster is it to type an ack command line vs. a find+xargs line? I wanted to time myself.

Inspired by this tweet by @climagic, I wanted to find out for myself. I used time read to see how long it would take me to type three different command lines.

The three command lines are:
A: ack --perl foo
B: find . -name '*.php' | xargs grep foo
C: find . -name '*.pl' -o -name '*.pm' | xargs grep foo

So I tried it out using time read. Note that it’s not actually executing the command, but measuring how long it takes to hit Enter.

$ time read
find . -name '*.pl' -o -name '*.pm' | xargs grep foo

real    0m8.648s
user    0m0.000s
sys     0m0.000s

For me, my timings came out to average about 1.4s for A, 6.1s for B and 8.6s for C. That was with practice. I also found that it is nearly impossible for me to type the punctuation-heavy B and C lines without making typos and having to correct them.

So I ask of you, dear readers, would you please try this little experiment yourself, and then post your results in the comments? Just give me numbers for A, B and C and then also include the name of your favorite Beatle so I know you actually read this. Also, if you have any insights as to why you think your results came out the way they did, please let me know.

At this point I’m just collecting data. It’s imperfect, but I’m OK with that.

  • Yes, I’m sure there’s another way I could do this timing. It might even be “better”, for some values of “better”.
  • Yes, I know that I’m asking people to report their own data and there may be observational bias.
  • Yes, I know I’m excluding Windows users from my sample.
  • Yes, I know it’s possible to create shell aliases for long command lines.
  • Yes, I know that the find command lines should be using find -print0 and xargs -0.
  • Yes, I know that some shells have globbing like **/*.{pl,pm}.

Note: I’ve heard from a zsh user that time doesn’t work for this because it’s a shell function, but /usr/bin/time does work.

Thanks for your help! I’ll report on results in a future post.

The world’s two worst variable names

April 18, 2012

As programmers, assigning names makes up a big part of our jobs. Phil Karlton said “There are only two hard things in Computer Science: cache invalidation and naming things.” It’s a hard problem, and it’s something we deal with every time we write a line of code. Whether it’s a variable or a table or a column in that table or a file on the filesystem, or what we call our projects and products, naming is a big deal.

Bad variable naming is everywhere. Maybe you’ll find variables that are too short to be adequately descriptive. The programmer might as well have been working in TRS-80 BASIC, where only the first two characters of variable names were significant, and we had to keep a handwritten lookup chart of names in a spiral notebook next to the keyboard.

Sometimes you’ll find variables where all vowels have been removed as a shortening technique, instead of simple truncation, so you have $cstmr instead of $cust. I sure hope you don’t have to distinguish the customers from costumers! Worse, $cstmr is harder to type because of the lack of vowels, and is no longer pronounceable in conversation.

There are also intentionally bad variable names, where the writer was more interested in being funny than clear. I’ve seen $crap as a loop variable, and a colleague tells of overhauling old code with a function called THE_LONE_RANGER_RIDES_AGAIN(). That’s not the type of bad variable name I mean.

While I’m well aware that variable naming conventions can often turn into a religious war, I’m entirely confident when I declare The World’s Worst Variable Name is $data.

Of course it’s data! That’s what variables contain! That’s all they ever contain. It’s like if you were packing up your belongings in moving boxes, and on the side you labeled the box “matter.”

Variable names should say what type of data they hold. Asking the question “what kind” is an easy way to enhance your variable naming. I once saw $data used when reading a record from a database table. The code was something like:

$data = read_record();
print "ID = ", $data["CUSTOMER_ID"];

Asking the question “what kind of $data?” turns up immediate ideas for renaming. $record would be a good start. $customer_record would be better still.

Vague names are the worst, but right behind them are naming related objects with nearly identical names that do not distinguish them. Therefore the World’s Second Worst Variable Name is: $data2.

More generally, any variable that relies on a numeral to distinguish it from a similar
variable needs to be refactored, immediately. Usually, you’ll see it like this:

$total = $price * $qty;
$total2 = $total - $discount;
$total2 += $total2 * $taxrate;

$total3 = $purchase_order_value + $available_credit;
if ( $total2 < $total3 ) {
    print "You can't afford this order.";
}

You can see this as an archaeological dig through the code. At one point, the code only figured out the total cost of the order, $total. If that’s all the code does, then $total is a fine name. Unfortunately, someone came along later, added code for handling discounts and tax rate, and took the lazy way out by putting it in $total2. Finally, someone added some checking against the total that the user can pay and named it $total3.

The real killer in this chunk of code is that if statement:

if ( $total2 < $total3 )

You can’t read that without going back to figure out how it was calculated. You have to look back up above to keep track of what’s what.

If you’re faced with naming something $total2, change the existing name to something more specific. Spend the five minutes to name the variables appropriately. This level of refactoring is one of the easiest, cheapest and safest forms of refactoring you can have, especially if the naming is confined to a single subroutine.

Let’s do a simple search-and-replace on the coding horror above:

$order_total = $price * $qty;
$payable_total = $order_total - $discount;
$payable_total += $payable_total * $taxrate;

$available_funds = $purchase_order_value + $available_credit;
if ( $payable_total < $available_funds ) {
    print "You can't afford this order.";
}

The only thing that changed was the variable names, and already it’s much easier to read. Now there’s no ambiguity as to what each of the _total variables means. And look what we found: The comparison in the if statement was reversed. Effective naming makes it obvious.

There is one exception to the rule that all variables ending with numerals are bad. If the entity itself is named with a number, then keep that as part of the name. It’s fine to use $sha1 for variable that holds a SHA-1 hash. It helps no one to rename it to $sha_one.

After I wrote the first version of this article, I created policies for Perl::Critic to check for these two naming problems. My add-on module Perl::Critic::Bangs includes two policies to check for these problems: ProhibitVagueNames and ProhibitNumberedNames.

What other naming sins drive you crazy? Have you created automated ways to detect them?

Undecided if something should go on your resume? Add more detail for guidance.

April 11, 2012

Convential Wisdom has it that resumes have to be written in the most clipped, stilted business-speak possible.  It’s not true.  Thinking that way is a disservice to our resumes and our job prospects.

A poster on Reddit asked how proficient he should be in German before listing it on his resume. You can see where he’s coming from. He’s wondering if he can add a “Languages spoken: German” bullet point to his resume, and that’s good. The problem is that the clipped business-speak mentality has him thinking that that’s all he can say.

You can and should add detail to your resume. The more detail you add, the less chance there is for misinterpretation, and it helps you think more about your skills and how you can sell them to the reader.

I suggest that instead of putting an overly terse “Languages spoken: German”, you add a sentence giving details. This might be, for example:

  • I am fluent in written and spoken German, and have been for the past 20 years.
  • I have conversational fluency with spoken German.
  • I know some German words I picked up from my Grandma.

If in the process of writing the details of your skill you find that it sounds silly, then you’ve answered your question as to whether it should be on your resume.  To be clear, that last bullet item isn’t worth putting on your resume.

This process works with any item you want to put on a resume.  As you add detail, does it still sound like it’s worth putting on there?  If not, leave it off.  If it is, work with that detail to grab the reader’s attention.

Programmers struggle with this all the time.  “How much Ruby do I have to know before I can put it on my resume?”  Add detail to answer your own question.  If you’re not going to be comfortable asking the question “How have you used Ruby?” in the interview, then don’t put it on a resume.

Finally, always remember why you have a resume: A resume exists to get the reader to call you in for an interview.  If something isn’t going to make the reader say “We need to get her in here ASAP”, then leave it off.

The legacy of Mike Wallace, 1918-2012

April 8, 2012

I have such fondness for people who keep doing what they do up to the very end. Like his “60 Minutes” colleague, Andy Rooney, who passed away in November, Mike kept working until the end. He was 93.

You youngsters may not believe this, but there was a time when “investigative journalism” meant more than a Unit 5 Special Report on people being overcharged on their cable bills. “60 Minutes” did actual investigations and asked the hard questions, like Mike Wallace digging into the lies of the Vietnam War.

Watch the clip below and ask yourself who today in journalism has this nose for pressing to find the truth behind the lies.

….

In my day job, I work for a company that sells books to school libraries. One day I visited the offices of the third largest public school district in the US, Chicago Public Schools, as an IT guy to talk about how we could improve their purchasing flow and, of course, get some of their business. The purchasing process was very involved and there was documentation about everything CPS bought, so that nobody could accuse tax dollars of being misused or misappropriated.

The head of the purchasing department told us, “I know this is detailed, but we can’t have any questions about where the money goes. I have to be be ready for the day Mike Wallace shows up at my office with a camera crew.” Such was Wallace’s reputation as the standard bearer for public scrutiny.

Mike Wallace, holder of feet to the fire, I salute you, and wish for more like you.

The nameless “they” and the Facebook & job interview trend that isn’t a trend

April 6, 2012

“I’m never eating there again,” he told me. “You know what they do?”

I was standing around at a party twenty years ago, and conversation got around to what our first jobs were. I said that my first job was at the McDonald’s, and someone in the circle looked stricken. “You couldn’t pay me to eat there. You know what they do there?” he asked. “I knew a guy who worked at McDonald’s, and he saw this other guy drop a hamburger patty on the floor by mistake, and he picked it up and put it on a burger and they served it. I’m never eating there again.”

The guy at the party had invoked the nameless “they,” as if McDonald’s tells its kitchen workers it’s OK to observe the five-second rule. Maybe he meant “they” to mean there was a secret cabal of grill workers who create Big Macs with special seasonings from the floor. He took the actions of one worker at one time to be an indicator of a trend. He nursed his horror and made sure everyone else knew about it.

But what if this tale of the dirty burger got on the news? Maybe the story would spread like wildfire across the country, with outraged citizens letting everyone else know about this horror. Maybe pundits would come out with columns excoriating the stupid practice of picking up hamburgers dropped on the floor, and why it’s bad for business. Maybe opportunistic politicians could beat their chests and call for a Justice Department inquest into this alarming trend.

Absurd, right? But that’s exactly what this non-trend of “job interviewers demand your Facebook password” is.

Over the past week, blogs and message boards and, of course, Facebook have been burning up with outrage at this non-trend. People commiserate and shake their heads grimly, imagining being stuck between the rock of having an employer snoop in our Facebook accounts and the hard place not having a job. People turn on Internet Tough Guy mode and imagine their defiance at the scenario, or give their theories as to the legalities of the practice. Business pundits weigh in on why it’s a bad idea.

The original AP news story that sparked this hullabaloo named one candidate, Justin Bassett, citing one interview at one unnamed company. That’s it. Still, it’s been rerun over and over and over. Every article has a similarly declarative headline like “Job seekers get asked in interviews to provide Facebook logins.” That’s as absurd as saying “McDonald’s serves burgers off the floor” because of the story the guy at the party told.

The news media have added non-facts, with one headline calling it a “growing trend”.
The follow-on news stories didn’t help. News media and bloggers snowballed it without doing further research. Even NPR, smarting from Mike Daisey’s fabrications, ran the story saying that “some companies” are asking for Facebook passwords. “Some companies” has as much to back it up as “they,” but it doesn’t sound so bad.

Senators have called on the DOJ and EEOC to launch investigations. (Also disturbing to me is Schumer’s assertion that in the job-seeking process, “all the power is on one side of the fence,” which only helps reinforce that incorrect idea.)

Is it plausible that this practice is widespread, and getting moreso? Sure, it’s plausible. Our privacy erodes every day, and millions of us do it through Facebook willingly. The story has the feel of truthiness. Doesn’t it just seem like the thing that Big Business would do to us? We already piss in cups to prove that we’re drug-free so that we can come in and shuffle paper.

To be sure, there are cited cases in that AP story of employers requiring access to candidates’ Facebook accounts. As Matthew Kauffman points out in his excellent probing of this story, those cases are of law enforcement and corrections departments, where greater scrutiny of candidates is common and expected. “In many of those cases, of course, applicants are also subjected to a full-on psychological evaluation,” Kauffman points out.

Kauffman’s aritcle isn’t alone in being sensible. An article on CNN.com says “The reason you haven’t come across any job interviewers asking for your Facebook password is that the practice is pretty rare.”

But how did this non-story get to this point? You got suckered in and the media ran with it.

When you heard this story, did you even question it? Or did you just forward it and post it as if it was an important life-saving story about there are these gang initiations and how “they” will kill anyone who flashes their lights?

It’s 2012, and we are the media. When we fan the flames of non-issues like this, we become the media that we should seek to leave behind.

Finally, in my job as blogger about employment and job interviews, I would be remiss in not addressing how to deal with a request for your Facebook credentials. I’ve read plenty of comments in threads suggesting walking out of the interview, or lying to the interviewer and saying you don’t have a Facebook account.

Walking out may feel good, as righteous indignation so often does, but it doesn’t help your situation. You give up any chance you had of getting the job. Lying is easily disproven, and. worst of all, requires you to lie.

The best answer is to calmly and respectfully say “I believe it’s best for business to keep business and personal life separate. That’s why I keep my private life private.” You may not get the job, but at least you’ll have been turned down while keeping a strong sense of ethics about you… which is more than you can say for companies that would ask to snoop in your private life.