The telephone game  seems to have happened to refactoring.  I subscribe to what would be consider the  ”classic” definition of  refactoring: the process of optimizing or extending a class  but leaving the existing exposed interface alone.  It seems that refactoring has been generalized from that definition into covering all activities related to touching old code.  Even worse, it has become an excuse to rework someone else’s code and then bitch about how bad it was.  Just look at the twitter stream for refactoring for a never-ending torrent of  abuse.

There is one simple way to tell if your efforts are truly a refactoring or not.  Did you break any of the unit tests?  If you did, then you are rewriting code instead of refactoring it and you had better update all the test cases while you’re at it.  Don’t get me wrong, there are times to rewrite software, but they are few and far between and, in my experience, it almost never pays off.

Refactoring isn’t just a nice philosophical idea; it supports one the most basic concepts in software development–backwards compatibility.  If you want to keep your customers and enjoy that paycheck, don’t break features or APIs in products without good reason or  get buy-in before release day.

To refactor the medical phrase “First, do no harm“, for developers it should be “First, break no test”.

Still, I miss old-school, printed computer books. It wasn’t so much what they contained, as what they quantified. Using the Rumsfeld model, a nice fat computer book helps me quantify the unknown unknowns. As I tackle a new body of knowledge – say a new language or IDE – the unknown unknowns are infinite. As soon as I have that book in my hand, the unknown unknowns turn into known unknowns. I now know how much I don’t know, and the table of contents is my new best friend – whether I read the book or not. It is hard to beat stretching out at the cottage with a refreshing beverage and the latest tome on source code analysis.

But software developers don’t typically think in linear ways. While many of us are college or university trained, in spite of years of classroom training we run away from learning new knowledge in the old school way. Developers search for the answer to their current problem, rather than accumulating knowledge for its own sake. They listen and watch communities, RSS feeds and blogs for trends. They look for on-line videos, podcasts, newsletters, and magazines. They may even find a book in PDF, and print out a few pages that they want to use for reference.

The challenge for technology companies is to make our collection of facts, tools and interfaces accessible without binding it all up in a single document with a cover. Wikis, on-line API tutorials, developer communities, and a host of other information bits need to replace the old book model.

Of course, it’s hard to argue with Groucho Marx, when he said “Outside of a dog, a book is man’s best friend. Inside of a dog it’s too dark to read.”

Fooled by the job description

So you are not really happy with your current position and you are starting to sniff around.  You might go to Monster and check out some of the jobs that are posted there. You may check out some companies’ websites and see what open positions they have.  Regardless of how you go about looking for a new job though, you will run into job descriptions.  There may be a few job descriptions out there that excite you and motivate you to apply because you can totally see yourself working for a company that writes such a perfect job description for you; however, the majority of them will cause your eyes to glaze over and probably bring on a few face splitting yawns.

Bear with us, there is reason to our insanity when it comes to job descriptions.  When recruiting for any position, but in particular for technical positions, we must pull together something that provides some guidance to job seekers.  And while I am at it, I will be completely honest and admit that sometimes I get the requirements for the position and realize I have no clue what the manager is talking about.  But the manager asked for it so it gets incorporated into the job description.

Job descriptions can be incredibly useful if you know what you are looking for.  They should give a feel of the company, the job and even the team.  I am sure you have all seen those blogs or websites that provide humorous takes on particular phrases, and admittedly some of those have a ring of truth to it.  Yes, sometimes seeing the term “start-up company” can be a rather unsubtle hint that the compensation package maybe more creative than you had bargained for.  “Team Player” can indicate that your team may be challenging and difficult to get along with or…it might mean that the manager wants someone who can play nice with others, because mean people do not do very well in that environment.

The job description does describe the ideal candidate, and really, we do not expect to see the ideal, but we do want a person who fits the job description.  For example, if the job description asks for 5-7 years in C/C++, and you have 3 years of C/C++, then by all means apply. If you have 0 years in C/C++, then do not apply.  The skills are listed there for a reason.

Since you are reading this, you may be on the Klocwork website.  If so, check out our careers section.  You might read a job description on there that appeals to you, and if you do, send us your resume.

“Do what the smart companies do,” says Mark Grice, a Klocwork Director and Manager of the International Reseller/Partner Network.

In our last discussion, Grice outlined three best practices for SCA tools selection: involve your developers, limit your selection to market-leading tools, and identify a deadline.

According to Grice, smart companies take those best practices and:

“After the six-month period,” says Grice, “a company will widen its deployment circle and get more licenses.”

On the other hand, Grice says it’s also possible that the company will decide to try another tool from their panel of tools. They won’t need to re-evaluate because they’ve got a short list to pull from.

“They don’t lose, whichever way it goes,” he says. “During that six-month period, they got value from that tool by applying it to their codebase, learning about SCA and cleaning up their code.”

Most software developer teams will face some form of remote development challenge during their careers or product cycles.  As demonstrated from the data above, the breakdown of remote need is as follows:

• 76% use some form of outsourcing,
• 64% have some developers  located outside of the main campus,
• 40% of reviews are conducted with remote participants.

You can’t let development come to a grinding halt simply because a critical team member is not physically available at the scheduled time or location.  For most organizations, code reviews need to be performed and employee travel is not the solution for cost and timing reasons.  This has driven the adoption of lightweight review processes and new tools that support it.

Klocwork built a code review tool for this express purpose.  Other ones exist like Code Collaborator and the open source Review Board .  How do you support your remote code reviews?  Email?  Wiki? Or a purpose-built tool like one of the ones mentioned?

There are 0010 0000 kinds of people in the world: Those that understand the difference between Big Endian and Little Endian, and those that do not.

Issues with Endianism and processor architecture ports are becoming more and more common these days as more desktop source code moves into different arenas.  Gone are the days when the 32-bit memory model or little-endian format dominate. Software changes are required to support the growth occurring not at the desktop, but in the server  and mobile platforms.

Mobile devices especially have opened a Pandora’s box of Endian and memory problems, with variety of processor architectures with ARM^[1] leading the way.  Add to this mix,  end-consumers are demanding desktop features like Adobe Flash or Office apps on mobile devices, many a stable codebase will fall apart when ported to either mobile or server.

For developers porting to different platforms, there are some significant challenges.  Just to list a few:

• CPU optimizations need to be reviewed
• inline assembly calls require rewriting or removal
• machine word (WORD) allocations may require refactoring
• any binary data exchanged over the network stacks require verification

None of these are  new, they’re just not a common skillset for most developers.

Source code analysis can be a boon in two ways. Firstly, in the planning phase by helping you determine the breadth of the effort,  and secondly by identifying any existing  issues, particularly of the memory allocation and Endian varieties.

For more in depth information, there are two recent articles available from Dr. Dobbs:

• Porting to 64-bit Platforms by Irving Rabin
• Detecting Endian Issues with Static Analysis Tools by Carl Ek

^[1] Note: Some ARM processors support both big and little Endian formats.

In terms of static analysis, one obvious measurement is simply the bug fixes you have made.  Most organizations have a number they use to define the cost savings for each bug.  Using some research data from IBM puts the cost of fixing a bug before a release at 40-50 times cheaper.   Fixing a bug after release is the extreme and hopefully you’re finding these issues earlier and that’s where static analysis comes in.

I would think any static analysis tool offering would give you that simple graph.  Below is a couple of examples where you can track the fixes per component or per owner.

Bug fixes per compoent

Bug fixes per owner

One other thing that I think is very important is where you’re saving money.  When you run static analysis for example you have a couple of choices where you can find defects.  After the integration build or right at the developers desktop before they check-in their code.  Obviously if the developers are finding and fixing their issues while they code and before they even get checked in then it is saving even more money for the company.  Good static analysis tools will help you see the value of using it at the desktop.  A simple counter is all you need to see how many bugs were fixed in the code prior to check-in.  Immediate ROI from using static analysis.

Mark Grice in a more peaceful moment.

The last time I spoke to the Klocwork Director and Manager of the International Reseller/Partner Network, he outlined 7 habits of highly ineffective Source Code Analysis (SCA) tool selection.

Among those terrible habits, he described an SCA tool-selection process that involved endless feature comparisons and massive checklists of irrelevant requirements.

His head almost exploded, but on this day our SCA guru was calmer.  Clearly, he’s been using relaxation techniques or drinking some of the good stuff, like acai juice.

According to Grice, successful SCA tool adoption involves three key steps:

1. Involve your developers in the process.
   “Developers understand what their requirements are,” Grice says. “And that means your selection criteria will be more realistic and achievable, and it will focus on what’s relevant to the organization’s software and environment. Developers are also best equipped to assess the SCA results.”
2. Limit your selection to market-leading tools with the functionality relevant to your software needs.
   “For example, if MISRA compliance is something you care about, then make that part of your selection criteria,” he says.
3. Have a game plan with a path and a defined end. Work toward a goal that’s realistic—spend enough time, but not forever, finding the tool (or tools) you need.
   “Have a good idea of what will constitute success, and be prepared to make a decision and move on,” Grice says. “Avoid paralysis analysis—unless your goal is to just waste time and money and contribute nothing to improving your software.”

That’s it for today. Grice is off to yoga class (um, or a pub). Stayed tuned for the next post in this series–How smart companies adopt SCA tools.

From this table (which has been a regular slide in our Agile in Action roadshow series) we see that tools can help, in this example just over 40 hours/iteration, which if you break that down further works out to about 1/2 day per developer every 2 weeks. Now that is an ROI that an agile development team can relate to…

What developers need is a tool that seamlessly integrates with their development environment and their workflow, so they can meet their quality goals without taking a big productivity hit.

It’s one thing to provide plug-in tools for the more popular IDEs like Visual Studio and Eclipse, but it’s an added bonus when defect detection is a seamless part of the edit cycle. No buttons to click, just continuous analysis and issue highlighting while you work.

Let’s take the analogy to the spell checker.  Initially, you had to click a button to spell check your document. That has obviously changed dramatically. Now we see any mistakes we make as we type them (and can even fix them automatically).

That’s what we were thinking when we introduced continuous analysis in our plug-in tools and our source viewer for command-line tools, Klocwork Desktop.

Here’s the spell checker equivalent for source code analysis:

The above screenshot is from our Visual Studio plug-in.

When you open or save a file, the analysis runs in the background. A bug marker in the left gutter and a squiggly line, in the true spirit of the spell checker, clearly marks the detected issue.

Find ‘em and fix’em while you work.

It was a mistake for Eric to wear a t-shirt to his job interview, and it was a bigger mistake to wear that particular t-shirt.

People who do not get hired after an interview second guess themselves; they look for concrete reasons as to why they were not hired for that particular job.  They might justify it by saying the company sucked, the interviewer was an HR douchebag, the hiring manager did not know their stuff.  Of course, they may be correct in passing these judgments, however, chances are there simply was a mismatch between the person interviewing and the company.  When this happens, count your blessings that the people doing the interviewing for the company knew that.  Being brought into a company that is a mismatch with your values and attitudes can impact everything you do, not to mention, make you downright miserable.

An interview is an opportunity for you to interview the company…to find out if you like them.  It is not just about sitting in front of some scary people and answering the questions they fire at you.   For most people, interviews are not pleasant experiences.  However, they are an evil necessity, until a more effective way of assessing people is invented.  And this brings me to the point of this blog…how the hell do you get through an interview?

1. Be prepared, know the names of the interviewers, know the company business and feel free to bring in notes.  It is entirely reasonable to request more information from the company representative setting up the interview.
2. Appear enthusiastic and interested (but not so much that you are confused with a salesperson!).
3. Dress appropriately.  This generally means clean trousers and a shirt with a collar, maybe a tie for the men, a clean skirt and a blouse for the women.
4. Answer the questions, and if you do not know the answer, let the interviewer know with the promise to get back to them.
5. ASK QUESTIONS…find out enough information to determine whether you want to be an employee.
6. Finally, follow up…if you like what you heard during the interview.  Just an e-mail will suffice, and believe me that will set you apart from 90% of the candidates.

Here’s some more data from the Forrester Consulting study commissioned by Klocwork that shows the majority of respondents still conduct in-person reviews… elsewhere in the survey only 36% of respondents indicated that they worked on a centralized team with everyone in one location. So that means, if 60% still conduct in-person reviews, they’re likely excluding valuable contributors to the review.

Data that shows majority still conduct in-person code reviews

Is this practice just being done because “that’s the way it is” or are there good reasons for in-person meetings being the primary way to review code? I could see the odd in-person meeting being necessary for a variety of reasons but given how distributed teams are these days and the variety of tools available to effectively review code remotely, it doesn’t seem that efficient.

There’s a general philosophy gaining more prominence around meeting reduction, whether in software development or elsewhere. We’re seeing many organizations question why their code review process needs to be in-person when it excludes people who aren’t co-located and generally takes up too much of people’s time. What are you seeing?

I have spent a career hiring, motivating, confusing, annoying and retaining developers.  I am not going to go so far as to say I understand you guys, but I do know what makes a good developer.  More importantly, I know what makes someone a bad fit for the team I am recruiting for.

First impressions are important. Yeah, I know, it sucks and your technical prowess should speak for itself, but it doesn’t.  Let’s face it, if you forget the “L” in Klocwork in your cover letter, I’m laughing too hard to pay attention to your superior coding skills.

If you continually refer to me as “Sir”, my feminist nose gets a bit out of joint; resumes filled with spelling errors throw into question your attention to detail and your level of concern for putting forth solid code.

While I am on the subject of resumes, it’s very impressive that people have the experience to fill up 15 pages of a resume. Maybe it’s even impressive that they have the time to type out a 15-page resume, but no one else has the time or the inclination to read a 15-page resume.  To date, the record length for a resume that I have received is 25 pages – this person is not employed here.

Being in this industry and in HR for as long as I have, I have learned something shocking – people stretch the truth on their resumes!  Imagine that!  And then imagine a company having the audacity to have someone in for an interview and test the person to assess whether what they claim on their resume is actually the case.  Of course, as a candidate, you should then take great offense to the fact that my colleagues and I called into question your integrity, your intelligence, and your worth as a citizen of the world.  In fact, you should probably follow up your interview with a strongly worded e-mail addressed to Sir at Kocwork.  Or maybe you shouldn’t.

Just…don’t…do…that.   We are not attacking your credibility. We do not enter the interview room thinking you are a lying, worthless waste of skin. In fact, we are pretty excited to meet you, so far we have liked what we have seen, otherwise you would not be here.

We will remain excited to meet you, right up to the point where you show up half an hour late, wearing a questionable outfit covered with what appears to be last week’s Sunday dinner.  Maybe you will look me in the eye, or maybe you will direct your eyes to my chest and keep them fixed there throughout the interview.  When that happens I like to observe where your eyes remain clamped when my male coworkers are interviewing you because inevitably it has nothing to do with what is on the interviewer’s chest. It’s just a convenient place to rest one’s gaze.  However,  between you and me, it kinda freaks me out.

I found this blog to be rather cathartic. I have more, so much more and if I am invited back as a guest blogger, maybe my therapy bills will go down.  Until we meet across a table in our interview room, I wish you good luck and good code!

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?

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…

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.

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.

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.

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?

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.

• 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.

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.

There are still tons of great rules you can apply even if you don’t make an embedded product.  But as I said before, it doesn’t make sense to turn on all the MISRA rules.  After running through many code bases and looking at the value of MISRA we certainly noticed a trend with a few culprits.  Here are a few examples that we found to be noisy with non-MISRA compliant code.

MISRA C 6.3 and MISRA C++ 3-9-2:

MISRA has the distinction of “required” rules and “advisory” rules.  This is an “advisory” rule.  Essentially it wants you to avoid using types like char, int, short, long etc. and to use specific length typedefs instead.  Obviously, many code bases use the basic types, so be prepared for many issues.

MISRA C 14.9 and MISRA C++ 6-4-1:

This is a “required” rule.  This rule  is really about making sure you have braces for your if/else keywords.  Good practice to have but how many of us really do this?

MISRA C 12.13 and MISRA C++ 5-2-10:

This is an “advisory” rule.  The rule doesn’t want you to mix increment and decrement operators into an expression.  This makes sense because it can be pretty confusing to read.  But in our experiments this seems to be something that many developers do.

MISRA C 17.4 and MISRA C++ 5-0-15:

This is a “required” rule.  The rule only wants to allow you to use array indexing for pointer arithmetic.  Everything else is non-compliant.

MISRA C 14.7 and MISRA C++ 6-6-5:

This is a “required” rule and another control flow example.  A function can only have one point of exit at the end of a function.  I can understand this but as you know, that is not reality.

MISRA C 13.2:

This is an “advisory” rule.  It states that tests against zero should be made explicit.  In other words: if (x != 0) is the proper way, not if (x).  The exception to this is if the operand is Boolean.  I don’t know about you, but you can crown me the super wiener on this? I never make it explicit.

So if you plan to pick up MISRA on your existing project beware of these rules.  I’d like to hear if you do any of those things in your code base.