In the spirit of the FIFA 2010 World Cup, I thought it would be fitting to describe how software developers can relate to the game.

1. Announcers – Have you ever really listened to what the announcers say?  One of my favorite things to listen to is the very opinionated soccer announcers.  Some of the things they say just make me laugh.  For example, when the announcer was describing the uncertainty of the game – “There’s one thing for certain, there is no score.”  or in this year’s World Cup describing a slow and boring game – “It’s like they are playing in slow motion”.  I’m not saying developers are opinionated…no way ;).  One thing that is similar is the comments developers will put in the code.  One of my favorites:

//When I wrote this, only God and I understood what I was doing
//Now, God only knows

For more funny comments go here.

2. Money – Soccer players do what they love for vast amounts of money.  Developers do what they love…well okay maybe not the second part.




3. Vuvuzelas – whether you like them or not you are stuck with listening to hundreds of Vuvuzelas playing their merry tune.  Despite all the complaints it will continue to haunt spectators until the tournament ends.  So why is everyone blowing the god forsaken plastic tubes?  Well my first guess is that they are drunk, but I think mostly because it is fun.  So as a software developer you don’t get to blow on the vuvuzela but I bet you would want to when you finished your work or the latest complicated feature?  Hopefully this is not because you’re currently drunk.




4. The thumbs up – In a meeting I had with our customer advisory board there was one individual who kept giving the thumbs up.  I understood that he was voicing his agreement with what we were talking about but I never understood why it was always with the thumbs up…until the World Cup started.  Seems to be the universal sign for the soccer players to say “nice ball” or “good play”.




5. Drama – Have you ever noticed how the majority of soccer players act when they have been fouled?  They dive 10 feet in the air, roll 16 times and clutch their chest like they were just shot.  Okay maybe I’m exaggerating a little but the point here is that some of these players are under the impression that they may get nominated for the next Academy award.  How does this relate to the software developer?  Well think of the code review, who really likes hearing that their baby is ugly?

With the recent story that the iPad has inherent security vulnerabilities, I thought it might be an appropriate time to delve into the world of software security guidelines…but I must warn you, this blog will contain an abnormal amount of acronyms, and may not be suitable for all audiences.

When talking about software security guidelines, there are really 5 or 6 organizations that are leading the charge, and they include:

-          OWASP

-          SANS Institute

-          MITRE

-          PCI Security Standards Council

-          SEI

Let’s first look at OWASP. OWASP stands for Open Web Application Security Project, which is a not-for-profit charitable organization that is focused on improving the security of application software. They are probably best known for their Top 10 lists from 2004, 2007, and most recently 2010.

Next is the SANS Institute. SANS of course is a FLA that stands for SysAdmin, Audit, Networking, Security. The SANS Institute claims to be the most trusted source for computer security training, certification and research, and have been developing and releasing their Top 20 annually for the past 7 years or so.

The MITRE Corporation is a not-for-profit organization that was founded in the late 50’s, and has over 7,000 very smart dudes (65% have Masters or PhDs). MITRE has come up with their own security guideline as well, that is the CWE (Common Weakness Enumeration) and it provides a common language of discourse for discussing, finding and dealing with the causes of software security vulnerabilities as they are found in code, design, or system architecture. The CWE lists over 800 programming errors, design errors, and architectural errors that can lead to exploitable vulnerabilities. Interestingly, MITRE and SANS decided to collaborate to come up with the CWE Top 25, yet another “Top” list they have been putting together for the last couple of years.

The PCI Security Standards Council was founded by American Express, Discover Financial Services, JCB International, MasterCard Worldwide, and Visa, Inc. and is an open global forum for the ongoing development, enhancement, storage, dissemination and implementation of security standards for account data protection. The PCI SSC has come up with the PCI DSS, “a multifaceted security standard that includes requirements for security management, policies, procedures, network architecture, software design and other critical protective measures. This comprehensive standard is intended to help organizations proactively protect customer account data”.

Finally, there is the SEI (the Software Engineering Institute, which is a federally funded R&D center at CMU, aka Carnegie Mellon University). The SEI is home to CERT which was established in 1988 to address internet security problems and to find ways to reduce the number and impact of security breaches. CERT focuses on protection, detection, and response to attacks on networked computer systems. Surprisingly enough, CERT is not actually an acronym.

Neither PCI nor CERT has received the memo yet that in order to be cool, you have to have a “Top X” list…perhaps next year?

Now, not to be left out of the fun, the NCSD (National Cyber Security Division) of the DHS (Department of Homeland Security) has their own strategic initiative called BSI (Build Security In). The NCSD obviously wants to cover pretty much all the bases since, in addition to their own BSI, they also sponsor pretty much all of the other guidelines.

I would be remiss if I didn’t at least acknowledge a few other notables with respect to software security guidelines, and to make it more interesting, I will only provide the acronym. I challenge you to come up with the full name. So, a few others involved in security guidelines are NIST (who run a project called SAMATE, and also run an event called SATE, which BTW is also sponsored by DHS NCSD), WASC, and finally STIG. For fun, I’ll throw in CVE, even though it is not a guideline, but more of a dictionary or list that was put together by MITRE, and shockingly is sponsored by DHS NCSD. I’m starting to think that DHS wants to be everyone’s BFF.

Hopefully you’ve learned a little more about the alphabet soup of security guidelines out there. If you’re scratching your head thinking WTF, you’re probably not alone…

By the time users hit the help documentation, they’re already snarly. Yeah, some people read the documentation first before using the tool, but…

A lot of people just want to dive in and start using the tool. And when I’m stuck I want answers. Now, already!  You might think it’s stupid-user error and I might think it’s stupid software design, but who cares? I want help right NOW.

Troubleshooting information lives or dies by the search-and-I-better-frickin-find-what-I’m-looking-for mentality. How do we look for this help? We copy and paste error messages into a browser and search.

When my ideas about organizing  troubleshooting information compete with how Google finds stuff, Search Engine Optimization (SEO) carries the day.  Or at least it should. Of course, there are SEO factors that put help documentation at a disadvantage, but that’s another topic for another day and I’ll let Tom Johnson do the talking on that one.

What does this mean for me, a technical writer?

Well, if two (or 5) of our tools throw the same error message, I’m going to have one page for each error message and have instructions on that page that explain how to fix it in each tool. Yeah, it’s nice to have tool-specific help information, but Google gives more weight to page titles and URLs. For good measure, I’m going to repeat the error message in the body of the page and format it in bold or italics.

Sarah Maddox highlights elements of what makes a good error message (including some hilarious examples of bad ones), so no need for repetition.

Aside from clarity, what do I want in an error message?

Firstly, I’d like to be able to copy and paste it.

Secondly, I’d like the solution to be stated.

As an added bonus, I’d like to be provided with a link in that message that would bring me to the dialog where I can take remedial action. Then, I won’t even have to look for help information. I can just fix it. Here’s an example of one these helpful messages from our Eclipse plug-in:

See? Documentation not required. The solution is outlined, and you can click the link to get to the license dialog, where you can check your host and port information.

Hmmm. Maybe that would put me out of a job. Sergey, please change that message to:

ERROR:FROZEN:BAD LICENSE.

I have a mortgage to pay here.

So a while back, I explored where developers get their information.  Surprisingly, it is hard to find hard data on the subject.  As a bonus from a Forrester study commissioned by Klocwork into the habits of code review, part of  the data revealed developers’ use of social media tools.  When asked directly about their use of these tools to communicate with other developers, the majority polled would not choose a social media channel.

It just goes to show that yet again, software developers are a breed apart.  As an aside, as I was researching this topic, I found an interesting post on why Social Media Experts are poets, Software developers are novelist that delves into ideas on barrier-of-entry as related to quality-perception of creative tasks.

A while back, I talked about how I keep running into organizations that seem to go out of their way to make developers’ lives hell.  I’ve run into several examples where developers had to switch between different environments just to write and compile code.  That’s as productive as watching paint dry and as much fun as rearranging the deck chairs on the Titanic.

For teams that want to run source code analysis in these types of environments (or any kind of dev tooling, frankly)  it’s very difficult for vendors to support.  I did my usual PM grumbling about these environments but since that post exactly 1 year ago I’ve come to realize that these environments are a reality and we need to figure out a way to support them.  Maybe it’s not productive but organizations are making it work.  I’m sure they would even argue that they have made it productive (good luck to them).  It’s for this reason that Klocwork has given in and instead of pointing our finger and making fun (I swear I never did), we’ve decided that it’s in our best interest to make sure we provide these customers with the capability to run static analysis.

A couple of releases ago, Klocwork introduced a new tool called Klocwork Desktop that provides Klocwork command line users with the same graphical capabilities that one would get from Visual Studio or Eclipse.  This tool was great for users who never used an IDE.  With Klocwork’s 9.1 release we have extended Klocwork Desktop’s reach by providing a remote capability that’s designed to support the type of environments described above.  Using Klocwork Desktop in remote mode allows users to view their source and detected-issue information when Klocwork Desktop does not have direct access to source files or defects, yet still get the benefits of finding and fixing your defects before you check-in your code.

One really cool feature that is part of this is the “you’ve got mail” notification.  At first, I have to admit this is something that worried me.  If I had to label one thing as a productivity drain it was those annoying alerts you get of new email coming in.  Of course right in the middle of doing something important you get distracted by a new email with plans for the next party (or in my case hearing about the kids latest poop explosion).  The first thing I always do is turn it off.  But in the case of finding bugs while coding, it only makes sense to give you these notifications in a heartbeat.  So you can actually be writing code on some machine in Jakarta and automatically your machine in San Jose is alerting you of bugs.  Pretty neat stuff.

It’s often taken as read that developers think code reviews are just a pain in the behind. Maybe that sentiment is true when a developer’s sitting amongst his/her peers and getting interrogated on the quality of their code, but some of the data from a Forrester Consulting study commissioned by Klocwork seems to contradict that a bit. The survey asked software development professionals a whole bunch of questions related to code reviews (some of which we’ve referenced before) and here are two interesting data points that suggest developers see real benefits from code reviews.

So 79% of respondents indicate that, yes, code reviews have been effective at reducing the number of bugs found later in the development cycle. Furthermore, 43% state that code reviews have caused a fundamentally positive shift in their project’s direction. Cool.

Of course, in other parts of the survey, respondents complain about aspects of code review, in particular how time consuming and difficult they can be to implement consistently. Nonetheless, the data indicates that when organizations put their heads down and make them part of their development process, real benefits will be realized. So, the challenge is making them part of the process – of course we advocate a tools-based approach, making them more lightweight, and combining automation into your software verification strategy so that manual reviews aren’t the only technique being used to find implementation errors.

This data line-up with what you’re seeing within your organization?

Documentation is the castor oil of programming. The managers know it must be good, because programmers hate it so much. Gerald M. Weinberg

I used to be a strong believer in formal doc reviews. Distribute a draft, plan a meeting, and have everyone gather around the table. But in the last few years, my team has moved towards mostly meetingless reviews–because people hate review meetings (you know, like code reviews, only worse), because people haven’t always read the drafts when they get to the meeting, and because some of our dev team is overseas.

• First, we distributed PDFs and asked reviewers to submit comments in email or on a hard copy. For the overseas team, email was the only option. This is not fun for either the reviewer, who has to do a lot of copying and pasting and referring to page numbers, or for the writer.
• Then we tried Adobe Acrobat PDF reviews, which allowed all reviewers to comment on the same PDF and view others’ comments. This was a big improvement over the email method.
• Now that all of our product documentation is hosted on a MediaWiki-based site, we’ve asked reviewers to edit the pages themselves, or add comments to the Talk pages. This makes life much easier for both reviewers and writers.

Still, as Anne Gentle stresses in Conversation and Community, using a collaborative medium doesn’t guarantee that collaboration will happen.

How do we encourage developers and testers to “own” the documentation for their tools, and to think of help as part of the product? If we can get developers and testers to RTFM, the benefits are obvious. They understand the tools in a way that no one else does, so they’ll provide feedback that no one else can. And they’ll become familiar with the help for the tools they’re responsible for, so they’d know whether a change they’re making or testing would affect the help.

I thought up a few ways that might increase the amount of review feedback:

• Create review tasks in our Agile project tracking tool, XPlanner. A top-down approach, and I wasn’t enthusiastic about it. Kinda like the daily castor oil treatment.
• Make everyone’s MediaWiki user page into their doc review page; we’d add links to these pages and reviewers would be notified through email, then they could delete the link when they’ve reviewed it. A nice bottom-up approach, I thought, in the spirit of the wiki.

But encouraging collaboration may be less about tools and more about process. If we involve reviewers earlier, they can tell us what they think before we’ve written a draft. A draft takes a long time to review, and if a reviewer doesn’t like it, they might not provide any feedback at all.

As Donna L. Davis says in a review of Andreas Rüping’s Agile Documentation:

Documentation isn’t bad. But bad documentation is terrible.

Is reviewing docs worse than eating Brussels sprouts? Do you review docs when asked, or do you hide the invitations under the edge of your plate, hoping mom won’t notice? Is the help so bad that you can’t be bothered? Are you just too busy? Are you one of those people who never consults the help for tools you use? Do you think your users will be able to use the tools you’re developing or testing without the docs?

What would make you more inclined to “own” the help for the tools you’re developing or testing?

There’s a tradition in R&D management that goes something like this: “give them toys and they’ll be happy.” Typically this has meant the biggest monitors, or the fastest CPUs, or an egregiously unnecessary SLI GPU configuration (for, ahem, high capacity computation tasks, right…), or whatever the latest piece of hardware might be that catches the purchasing manager’s eye.

But what about the software on that hardware? Sure, we equip people with an IDE (if they’ll use it, or whatever text editor they demand if they won’t) and whatever other tools are mandated as part of their development lifecycle. In fact, typical managers would dearly love to be able to mandate more tools for their developers. It’s easy, after all, for a manager to make the correlation that more toys = happy developer = more productivity = more code = bigger bonus = happy manager.

So why do so many developers, particularly in the embedded space, use outdated software tools? What’s the excuse, after all, for vi or some close derivative being a dominant code editor?

Inverse snobbery has been a popular theme in the privileged parts of the world for much of the last thirty years. “Yes, we drive a Lada because we just don’t believe that a BMW is necessary.” Really? Does anybody actually believe that tripe? I mean, I can well believe “I use vi because I have to; it’s the only editor that works on this cruddy piece of hardware.” But forgive me if I have a hard time with “I use vi because I like it better than anything else.” We all get used to stuff that makes no real sense, but surely there’s a point where even the most inverted technical snob has to look themselves in the mirror and know, deep in their darkest most hidden-away recesses of existential reality, that they’re just full of it.

Intransigence. Inertia. Feet dug in harder than you could possibly shift in a lifetime. Call it what you will, but unless something life-changing, like a project in a new language happens, many developers have a nasty habit of sticking with what they know. “What we do is hard enough,” goes the meme, “we don’t need to make it any worse.”

So how are those same developers coping with the demands of the ever-increasing footprint that is professional development? After all, it’s not enough anymore to simply bang out some code and check it in, moving on to the next assignment and hoping nobody notices. Now the professional developer is tasked with unit testing, performance testing, static analysis, memory profiling, code review, refactoring for maintenance, architectural cohesion, you name it. The list only ever gets longer as we move the goal posts for QA closer and closer to the consumer, requiring the developer to pick up the slack in the interim.

How does that footprint get coverage? There are still the same number of hours in the day, and the required amount of code generated by each developer hasn’t markedly decreased over the last 10 years. So what gives? One thing’s for sure… vi hasn’t made developer productivity much better than when it was first written at Berkley all those years ago (with all due deference to the strides made by vim/gvim in recent years).

I’m going to examine several different communities in upcoming posts and look at the approach they take to solving this problem, covering a range of backgrounds and roles from embedded driver writers to creators of modern web applications. In the meantime, have a look inside yourself and, if you pass muster as some analog of the crusty vi user I paint above, ask yourself why, and what might make you change. Recent history abounds with case studies, some of which I’ll reference, but at the end of the day it’s all about you and your personal work practice.

Just returned from my second stint on the Agile in Action roadshow with our friends from Electric Cloud, Perforce, and VersionOne, this time visiting the cities of Toronto, Philadelphia and Chicago. Rather than going into minute detail (and the fact it is a Friday afternoon before a long weekend), I thought I would share a few random observations from this trip:

• Organizations (and individuals) are begging for as much information and guidance as they can get on Agile and tools for Agile, and are willing to give up a days in the office and brave horrific traffic to get it
• Teams that are 6 to 9 months practicing Agile think they’re novices, but in reality are seasoned veterans and have lived through most of the nightmares newer teams are currently facing
• Toronto cab drivers have a random-number generator for their “flat-rate” fares from the airport
• The majority of our audience would rank low to medium on both their knowledge and their adoption of Agile…they all want to go Agile, they just don’t know where to start (or if they were started, how they could improve things)
• Window seats suck, but not as much as middle seats
• Developers do code reviews, but don’t like doing them…
• …but you could always count of the one guy in the audience who claimed to like them…obviously someone’s living in denial
• And finally, if you are in 3 different hotels in 3 nights, keep the sleeve your room key comes in on you at all times…I guarantee you’ll forget your room number at least once during the trip.

What is the ROI to the company for developer tools?  This has always been and continues to be a struggle in any development organization. Developer productivity to date has been very poorly measured and studied. Programming has always been a creative task bound within the constraints of  a framework.  Many people have tried to measure direct individual developer productivity with less than convincing results:

Bugs per dev, bugs per team, bug regression rates, bug trend lines, comparative .NET Framework book sales rates,  # of [static analysis] violations per kloc, etc, etc.. the list is really endless…

So when it comes to assessing the value of development tools, what are the motivational and productivity drivers?  During my time as a development manager, my focus was always on reducing roadblocks and mindless repetitive tasks.  When you are well compensating developers to use their grey matter, you don’t want their efforts to be wasted on the simple stuff.

Focusing on a bottom-up approach, I base the tool choices on the marginal cost for adding a developer.  After getting the basics out of the way, including corporate overhead, dev box, standard  software load and a complier, what’s next?

Well, there are a plethora of vendors all screaming at you to buy their product, but let’s take a step back and look at what makes a developer produce better code.

Here is my list in order and why.  It starts at the developer desktop and depends on frequency of use and then spreads out to the rest of the development team:

• Source control (with nightly backups) – Even for a development team of one, don’t leave home without it.  The benefits of source control really can’t be overstated: revision control, easy diffs, build integration, product branching  and maintenance, etc.

• static analysis – like grammar checking for Office but so much deeper. It has been proven time and time again that getting rid of the minor flaws and style inconsistencies right when the developer is working and the code is fresh in their brain is the most productive.  Waiting 2 hours, a  day and for some even a week costs a context switch.  When you add in the regression analysis for the maintainability, this tool just shines and pays for itself quickly

• Issue tracking – some might debate that this tool’s placement should be above static analysis, but as I said,  my focus here is on the developer’s desktop and not team or management needs.

• refactoring – only sightly better than find/search/replace - not essential but when used frequently and consistently can be used for good productivity benefits .  It’s one of the small tools that get you through the day.

• code review – similar to static analysis but now we have widened our view off of the desktop and include the team to build better code. No one person can know everything and extra pairs of eyes on the code is only going to make it better.

• unit testing – anything to take away the drudgery of building simple test cases that completely cover the class/api interfaces and maintaining with the refactoring that will happen over time.  You might ask why unit testing is lower on the list. Simple. You can’t test code that has not been written yet.

• dynamic/performance profiling and input injection – your customer will like you for this one.  Over time, most applications grow, add new features and become sluggish pigs.  Version performance testing and making critical judgments in trading off performance for value is one of the  keys to repeat customers.

There you have it.  A list of tools for developers (note I said developers not PMs or teams) that I consider essential to have on each desktop to get them through their day.