15 workplace barriers to better code

Meetings, know-nothing managers, productivity metrics -- here's what's standing between you and the next generation of great software

Page 4 of 5

Programming productivity obstacle No. 10: Poor documentation

Writing documentation takes time. But we're paid to write code. We're often measured by the lines of code we generate. You want results. We're just doing what you want. Don't worry, we'll remember it all and write it down eventually.

Sometimes there's plenty of documentation, but it's for a version of the code that is months or years old. Did I say that this method stores the data in the Foo table? My bad. That was two generations ago, and we haven't had time to work through the code and fix those old notes. But we'll get to it -- honest.

Programming productivity obstacle No. 11: Slavish devotion to documentation

While we've all experienced projects with no documentation, it's common for projects to fail with too much verbiage and too little coding. I've had several people show me a shelf filled with binders and say, "They were paid by the pound for their documentation." Reading it all would take a year.

Programmers often handle the requirement to write a comment like they handle discussing "Battlestar Galactica" or "Dr. Who." They write endless pages filled with minute details without summarizing or getting to the point. This can be deadly in the documentation when they don't offer much abstraction or understanding, just a regurgitation of what the code does. They're not illuminating; they're just transliterating the code into English.

Programming productivity obstacle No. 12: Distraction-rich environment

One client insisted that I come into their office every day. Then they insisted that I use their PC, which could not be customized for a week. Then they didn't have any office space, so I was plopped into a converted conference room with six interns, who would spend half of their day talking about what happened the night before. The other half was devoted to figuring out what they would do that evening. While it was entertaining, I got little work done.

While sales and marketing teams can function and even thrive with some background noise, programmers often need library-like silence. The idle chatter, distracted tapping, or ringtones will snap the programmer's brain out of the abstract work zone and back into reality. Then it takes a few minutes to get the brain where it needs to be.

One developer told me he hated his new desk because it was three feet closer to the air-conditioning vent, which was, he said, incredibly loud. Three feet and it was ruining his concentration. This may be humorous, but it's true.

While many businesses indulge programmers with kinetic toys like ping-pong tables, they often forget that developers need silence to concentrate. Yet they pack the programmers into big rooms and assume this is collaborative fun.

Programming productivity obstacle No. 13: "Cultural fit"

Do you want your own office? Or do you want to be in a team room where you can shout out your questions? Do you like to start work early in the morning, or do you want to stay late?

Every team works better if the people have a similar style. The teams that can't find a common ground quickly fail. The communication never happens, and they end up working at cross-purposes.

While it's tempting to generalize and say quiet offices or bullpens are superior, it's better to leave that to the team. I've found it's great to have everyone in earshot when you're doing plenty of low-grade upkeep and building out infrastructure. If someone yells to someone else, it's not much of an interruption when you're waiting for a compiler or a build to finish. Sometimes I'll even know the answer. A general call to everyone can be very efficient.

But if I'm creating a complex algorithm with many moving parts, the interruptions, talk, and even keyboard tapping really keep me from concentrating. That's when I want my own quiet office.

| 1 2 3 4 5 Page 4
From CIO: 8 Free Online Courses to Grow Your Tech Skills
View Comments
Join the discussion
Be the first to comment on this article. Our Commenting Policies