Refactoring is a vital component for software developers, helping to prevent their projects from becoming unusable, and unmaintainable spaghetti code. Equally important to some developers, is the notion of refuctoring…check out this tongue in cheek look at Refactoring vs. Refuctoring. Be sure to check out the slide deck at the end.

Refuctoring describes the process of making your code unmaintainable by anybody but yourself.  I love some of the examples of Refuctoring such as “Pig Latin”, “Treasure Hunt” and my personal favorite “Stating the Bleeding Obvious”:

For example:

//initialize a to 1
int a=1;

Not that I’d ever do that (pause while I go clean up some code). Ahem, right anyways I thought I’d throw out some other refuctorings:

1.    “Catch me if you can” – Use so many goto statements that it will make anyone’s head spin.  Especially when you start adding backward goto’s.  Take a look at the CVS source code,  they have some nice (nasty) examples.

2.    “Giant tar pit of hell” – This is hard to blame one single developer as it really encompasses many developers getting together to create one big cohesive piece of crap.  You know you have a problem when you run out of printer toner trying to print these.

"Giant tar pit of hell"

3.    “WTF” – Using names that no one will know…ever.  If you create a bankaccount object, instead of calling it ‘x’, here’s a wild idea, why not call it ‘bankaccount’.  Let’s face it we are all guilty of this.

Now if you really want to be special (I don’t mean in a good way), try combining #1 and #3:

int afunction()
{

there:
   ...
   if(something)
   {
      goto here;
   }
   if(somethingelse)
   {
      goto there;
   }
here:
   ...
   if(somethingelseagain)
   {
   goto end;
   }
end:
...
return;
}

I have to admit, I’m not winning any awards either. It is certainly time to get on the refactoring bandwagon.

Part II – Joy is the word…

OK, so Grease is really the word, but it didn’t fit my theme, gimme a break… Anyway, back on topic, since Joy of code review – part one of this series was published last year we’ve seen our new code review product in action in a variety of customer and prospect situations, and much like the eponymous hair product in the musical mentioned above, what we thought of as an interesting twist on an existing paradigm has turned into a bit of a barn burner. I refer, in this case, to the notion of what constitutes a code review if you remove the formalism of the invite from the process.

Consider what I’ll call, for the sake of being what marketers insist on terming “edgy” (for no really good reason as far as I can make out), old fashioned code reviews. You know the type, we talk about how we really should do more of them all the time. Check in your code, mail out a bunch of invites, mail some more when those get declined, gather around a table, project your code and wait for the insults to come rolling in.

You want to try that again, Mr. Coding Specialist...?

On the down side of these things are all the obvious problems… People don’t like getting reviewed, and unless you have a particularly unpleasant architect, the reviewer is no happier about being in the room than the person on the sharp end. Factor in the time, the annoyance of the arrangements, the opportunity cost of yanking the architect away from whatever they were previously doing, and you’ve got a really expensive, not very productive, but very important from a pointy-haired-manager-perspective process.

It’s really the classical no-win situation. Your manager requires it to be done. You hate it, and you know everybody else in the room hates it too. It’s like a giant dose of spinach to a five year old – doesn’t matter how good it is for you, you’d rather scream and sit in the naughty chair all day than let that stuff past your lips.

So when we were thinking about changing the approach to code review, it seemed obvious to us that whilst code review itself is valuable, the means by which it gets accomplished is fundamentally broken. Factor in peoples’ unthinking delight when confronted with anything social and what the heck, we figured, let’s turn the whole thing on its head. Instead of going top-down into a software organization and helping the manager enforce something unpleasant in an all new and collaborative-y, enterprise-y way, how about reaching out and encouraging bottom-up engagement through a model that people are comfortable with anyway, namely formless (a.k.a. social) communities.

Who’s the most obvious person to review the code of a good developer, after all? It might be their architect, but the chances of a good developer making a blunder of the architectural type (or any kind of dumb error) is probably reasonably low. Not saying it doesn’t happen, but we pay people at that level a good amount of money on the understanding that they produce decent code, so why then treat them like kids? Instead, if the code produced by that guy is made available for anybody to review, quite literally, then rather than getting the architect grumpy because he’d rather be thinking about the next huge money maker than what this guy happened to have done mostly right but nit-pickingly-wrong in this one situation, you get other team members taking part who have (in most cases) more useful input to impart anyway.

Instead of feedback of the “so… rather than using that particular transitive constructor, I’ve found that explicitly instantiating a new object and then initializing only what I need saves me, on average, 3 cycles a day” type, you might get the “hey, I was hacking on that a while back… might want to filter that data, cuz Bob’s front end passes in all kinds of crap… just saying” type instead – your choice, but personally I’d rather hear an hour’s worth of the latter than a moment’s worth of the former…

So who is at the review turns out to be much more important than whether it’s held, given some arbitrary set of “holding” conditions. But of course this comes with its own set of challenges, notably how do you know when you’re done if there’s no formal “meeting” to review your code (and to insult you, have we mentioned that part?).

In fact, it’s much like how the transition from waterfall to Agile was accompanied by many a gnashing of management gums and misplaced wails of “but how will I know if it’s going to be done on time?” But hey, that didn’t work out so bad, did it? People got used to time boxing, to changing requirement sets, to not waiting until it was arbitrarily “finished” and instead shipping it so as to gather feedback faster.

In my next post I’ll look at this new world order from the top down and examine the benefits to encouraging (rather than imposing) a social code review paradigm, and how it can make those metrics we know you care about look better than ever before.

How do you measure your software?  There are simple metrics that help with quality, such as keeping track of the number of bugs or security vulnerabilities in your system.  Trending these metrics is a no-brainer. When trending is in place, action can be taken because everyone knows 6 security vulnerabilities is worse than 5.  But what about other types of software metrics (and there are many)?  Have you ever heard of a maintainability metric? Halstead program volume? McCabe cyclomatic complexity?  Coupling/Cohesion?  The question becomes what do you do with these metrics and are they valuable?

Choosing a metric will really depend on what you’re after.  A good reason for measuring your code is to get predictable quality.   If you don’t have a metric in mind, the easiest place to start is with McCabe’s cyclomatic complexity metric.  I’ve seen many software organizations implement this as a good measure to help predict system “complexity”.  In other words, to help them understand where they may need to refactor or redesign their code.  McCabe cyclomatic complexity uses a measure of the linearly independent paths in the source code and is measured on functions or methods.

McCabe’s Cyclomatic complexity uses values to define what is complex.  Something greater than 20 is considered very complex.  You should think about re-writing that function because it is getting out of control.  Since the inception of McCabe’s Cyclomatic complexity metric,  several other variations have appeared, including Extended Cyclomatic Complexity and Plain Cyclomatic Complexity.  Back to the question, with so many metrics, which ones do you use and are they valuable?

No one can answer that question. In fact, software metrics is quite ambiguous.  It is hard to find anyone who says,’Thou shall use metric “x” because it will help you improve quality by “y” amount.’  The value “x” and “y” just don’t exist (although many have tried to put some data together).  Even more ambiguous are the values that may be defined with these metrics.  Don’t get caught up with these values; they are really arbitrary.  I’ve run into organizations where the majority of their code was deemed “very complex”.  Does this mean they should redesign their entire code base?  Certainly not. These numbers will vary depending on what you’re building.  So be careful if you use the “recommended” values for any metric.

Instead of focusing on the value of your next metric, what you really should be doing is trending that metric.  Find out if that value went up or down.  Up bad; down good.   Taking it one step further (if you really have a “thing” for the values), you could start by finding the standard deviation of your metrics.  In other words, find the average value of any metric, say complexity, plus the standard deviation.  Now, you can keep track of that value knowing that if you go outside your bounds of deviation, then you may want to look.

Software metrics certainly have their place and can help give some predictability on your system.  In another post, I’ll talk about how you can take some low level metrics for the developers and give them insight into the software system.

The not-so-agile technical writer

I’m a technical writer who’s a big picture kind of person and that means agile development is sheer torture for me.

Going into my second agile project, I thought I would be able to go with the “flow” a bit more. I was wrong.

But, it’s important to point out that our documentation team hit all of our deadlines for new features, while substantially rewriting our help set and moving it to a wiki. I’m pleased with the outcome, but the trip was not pleasant.

This will be my first post in a series about technical writing in an agile environment. Today’s post outlines the obstacles that I face—aspects of being me (mostly). The next post will outline my coping mechanisms, as well as our team’s plan for our next project.

If there’s no follow-up post, that means that my unbridled honesty has gotten my keester kicked to the curb.

Waterfall nostalgia

I got started on this tech writing gig as a consultant. The product would be a month or two away from release, but mostly fleshed out and I’d swan in, grab the requirements documentation and the design specifications (sometimes I’d write those), play around with the tool and voilà: a manual. I could be very single minded about what I was writing and just get it done.

To be clear, I’m in no way saying that the waterfall method delivered better products or documentation, just that I had a better view of where we were going.

With agile, I feel like I’m jumping hither and yon doing all these minute tasks, with very little view of how they’re supposed to fit together. I’d often snarl to my manager after meetings that “I’m given a doorknob, a shingle and a shrub and told to go build a house with them.”

In fact, in his blog post about minimalist documentation and agile, Shannon Greywalker hits on my problem very accurately, and it’s this: “user stories are typically too granular” for minimalist documentation. Minimalist documentation, as he says, requires the “35,000 foot view”.

And what I want runs counter to the whole agile methodology: THE BIG PICTURE RIGHT NOW.

Multi-tasking versus uni-tasking

Another problem I face is that I’m a uni-tasker; I like to finish what I start—not doable when features span several development iterations and are in major flux.

There are blogs out there about what Generation Y is like, good or bad, but the one thing I do envy is their multi-tasking ability. These folks grew up doing homework, while downloading music and instant messaging their friends.

That’s the kind of splintered attention I envy. So, I got David Allen’s book, Getting Things Done, but I couldn’t finish it. I read the line about having “a mind like water” and then froze. Uh-oh. Mind like ice. When I think of my work and personal to-do lists, I’m paralyzed.

So, I signed up for meditation classes and I’m now making another attempt to read Getting Things Done. I’m hoping it’ll help me switch directions faster. Not easy when you feel like the Titanic and need an hour’s notice to hang left. Now that I think about it, the Titanic is a career-limiting metaphor.

Procrastination

Now it’s time for confession. Our documentation department fought for and won a two-week offset for our last two projects. Yep, that’s right, we trailed development by a two-week iteration.  It’s amazing that we haven’t been rounded up and thrown in agile jail.

By procrastinating this way, we hoped that features would be more fleshed out before we started writing about them. It was our vain hope that this would contain some of the rewriting efforts. We still did a lot of rewriting, but this round we were rewriting a lot of material for the wiki anyway, so the offset didn’t matter that much.

By now, you’re probably thinking that it must be very hard being me. Don’t cry for me, Costa Rica; I have ways of getting by. Tune in whenever the next post surfaces to find out how I cope and how I hope to improve.

I just couldn’t resist using the classic spaghetti Western as the title for this instalment of my Going Agile series because it a) it was an awesome movie, and b) it truly sums up that 1^st iteration of ours. My last post was all about the 1^st iteration planning meeting, and how it was such an exciting and productive time for our team. We came out of that meeting a little weary, but extremely motivated to get to work. We were also just a tad naive.

The next 2 weeks were a roller coaster as we cut our teeth with Scrum. First the good:

• Communication: the interaction amongst the team members was definitely improved. If someone needed an answer to something, they immediately sought out help. The team realized that if they didn’t get timely answers, tasks wouldn’t get done. They really didn’t want to say those dreaded 2 words, “nothing finished”, in the daily scrum meeting.
• Meetings: The daily Scrum meetings were kept short and  sweet as everyone said what tasks they had finished, what they were working on, and if there were any roadblocks in the way. If something required further discussion, a break out meeting with the appropriate people was held.
• Energy: This was a high performing team to begin with, but there was now a newfound energy and buzz. This was a fun team to be around!

As the title suggests, there certainly was some bad in that first iteration.

• Testing and documentation: These were the 2 areas that struggled the most in the first iteration (and the next couple as well). They felt that their work was too heavily back loaded, that is, they would receive their stuff too late in the iteration to either test or document properly. Many of the stories were not totally Done because they were either not tested properly or documented with the time they were given.
• Defects and bugs: Because testing happened so late in the iteration, many of the bugs they found could not be addressed in that iteration. These bugs would have to be carried over to the next iteration, meaning the number of new stories would have to be reduced.

Now for the ugly.

• After just a day or so into the iteration, a plethora of unplanned tasks starting showing up on the Scrum board for many of the stories. These stories now had many new hours of tasks added to them, and we fell behind very quickly. This leads into the next ugly…
• The Burndown chart: Talk about a misnomer! We started to affectionately call our chart the burn-up chart, because there was very little down direction going on with it. Our chart would have looked great at a sales meeting, but in our Scrum meeting, not so much.

So as you can see our 1^st iteration had its share of warts, and in fact, the next couple did as well. But we didn’t get frustrated. We learned from our mistakes and changed/added things based on those mistakes. The Retrospective meetings were incredibly useful because they made us all take a hard, honest look at what went well, and what didn’t. The next, and last entry in my Going Agile series will look at the Retrospective meeting.

Now that the New Year is upon us, I thought it would be a good time to add another chapter to my Going Agile series. My last entry left off at the point where we had prepared our backlog, created team rules and defined “Done”. Now we were ready for our first Iteration Planning meeting.

In our “team room” we had all the essentials in place for this meeting: stacks of color-coded cards (for capturing the various to do’s, or tasks), pens and highlighters, our Scrum board (with pins) to stick our tasks onto, and a keg of Red Bull, because we had no clue as to how long this meeting was going to last.

Everyone was anxious to get started, so I (as the Product Owner) introduced the first story that we were going to work on. I gave as much detail as I could about what the feature was, what it should do, the benefits the users would get from it, and so on. The team asked questions, and I answered them as best I could.

Once I was done talking, the most remarkable thing happened:  the team started to write down the various tasks required to complete the story. It started off quietly, as all the team members started writing on their cards, and to be honest, I was a little concerned that this was going to be the way this meeting would go. (Where’s the Red Bull, because this is shaping up to be a long and painful session.) But then the questions started coming from all sides –developers asking other developers questions, testers asking developers questions, documentation asking developers questions, developers asking testers questions, follow up questions, and so on. I vividly remember watching this, and the frenetic pace at which things were happening. I had worked with this team for a few years (doing Waterfall development), but I had never seen this level and intensity of communication and cooperation from the team. Once all the questions were asked (and answered), the task cards were collected and posted to our Scrum board. On to the next story, rinse and repeat…

The meeting lasted another few hours as we worked our way down the backlog and watched the new tasks go up on the Scrum board. By the end of the meeting, we were ready to start our Iteration. As the team left the room, they each moved a task from the “To Do” column to the ‘In Progress’ column, and the Iteration was underway.

It was truly incredible to see this team come together and work as a team so quickly, and to see how motivated they were to move to this new way of developing software. The next chapter in this series will look at the trials and tribulations of that first iteration.

In my previous blog post, we talked about the value of compiler warnings and reasons to have source code analysis. Now, I’d like to get into the value of coding standards and touch on how you can fit this altogether.

Coding standards are a set of rules or guidelines usually created as part of an industry. The goal is simple, provide guidelines, so you can create better code and increase your code quality. Probably the most common coding standard I run into is called MISRA C. This is a standard created for C code in 1998 and revised in 2004. A new standard from MISRA was released in 2008 for C++ code. MISRA was developed for the Motor Industry but has since been adopted by many other industries. Other coding standards such as Joint Strike Fighter are focused on other industries, such as the aerospace world.  And there are more generic types of guidelines, such as the Power of 10, which contains more high level practices.

Either way, these standards cover everything from simply “thou shall comment code” to more specific coding no-no’s. So, how do you apply these to your process?

The advantage of these coding standards is that compliance is something you can quickly scan for using source code analysis. Any source code analysis tool worth its salt incorporates these standards into their issue checkers.

Implementing a solution for developers is key to this process. After developers check to ensure there are no compiler errors (or warnings!) they can run another process (or integrate into your existing process) using source code analysis techniques to find infractions with various coding standards in the code.

Remember that compiler warnings can be very helpful, so use them. Don’t be surprised when your source code analysis vendor asks if you are using your compiler warnings on your next checker feature request. Once you have cleaned up your compiler warnings and you want to take the next step to improve code quality, there are many good coding standards that will bring up the quality of your code. Use source code analysis tools to help you automate this process and you will guarantee a better report card.

I had a chance to speak with Bruce Swope, the VP of Engineering at SterlingTech, an ISO13485 Registered full-service medical device software organization offering software development and validation services. SterlingTech has developed software for an array of medical products including implantable devices as well as external support and monitoring equipment. Their team has worked on Class I, II, and III devices that resulted in successful FDA 510(k)s, PMAs, and CE submissions. 

Bruce has extensive experience in medical device software development and he is an expert in leading Class III medical software products to commercial release. His depth of experience also spans the development of enterprise solutions, security applications, internal applications, and process control systems. He has been an early adopter of quality practices including ISO 9000 processes, Common Criteria Certification and Capability Maturity Model implementation.

I wanted to talk to him more about the challenges developing software in an FDA-regulated context and what all this means to medical device software development teams.

[Brendan] Given your experience working with a variety of medical device companies, what do you see as the biggest business challenge they face?

[Bruce] The biggest challenge is developing a medical product in a cost effective manner that meets FDA and international regulatory regulations.  Most companies have very limited resources available and have boards or investors that are not used to the rigors of regulated development.  This often leads to a gap between investor expectations and the reality of getting the product ready for market.

[Brendan] What about technology challenges?

[Bruce] The hardware platforms that the systems are developed for are very expensive in time and money to update once fielded.  Often, the hardware is impossible to update without dramatic impact to the patient such as surgery.  This creates a need for software developers to find creative ways to extend the life of the hardware by introducing new functionality without updating the hardware. This can often cause the software to become much more complex than planned.

Further, device manufacturers must balance the expectations of customers against the rigor and security required with making a medical product.  Consumers are very accustomed to seeing feature rich devices reach the palm of their hand and wonder why their heart pump can’t double as a PDA or MP3 player or why they can’t plug their device into the internet to download new alarm tones.   

[Brendan] What’s the most common problem your firm is hired to solve?

[Bruce] Many of our customers are looking for an organization that has experience in working with a given technology to create a product that will be approved by the FDA and international regulatory authorities. They are looking for someone that has the experience to deliver a quality product and a complete design history file without wasted effort or significant delays.

[Brendan] In your experience, do most medical device companies have a clear understanding of the regulatory environment or is there still confusion in the market?

[Bruce] Many of our customers are early stage companies that are looking for us to provide the knowledge of the regulatory environment.  Other clients may have an understanding of some aspects of the regulatory environment such as mechanical or electrical but need assistance with the software aspects.

Unless companies invest in dedicated regulatory resources early on and get the FDA or notified body involved sooner rather than later, there will always be confusion and opportunity to misdirect effort.

[Brendan] Any common misconceptions related to compliance issues you can share?

[Bruce] Companies have come to us with a misunderstanding of the impact “level of the concern” will have on the development process for their proposed device.  Companies will often put in place a Quality System that is overly burdensome on the software development process. 

The result of these mistakes is often that either too much or too little is done to develop the software.  Either outcome is damaging.  In the case where too much is done, extra cost is incurred and the project completion and entry to the market is delayed.  In the case where too little is done, a rejected submission could result leading to further cost and delays. 

[Brendan] What’s the #1 recommendation you give to clients as it relates to the intersection of compliance issues and software development?

[Bruce] Make sure that your company has a good solid Quality System as it applies to software development. Do not put a Quality System into place that you can not follow. This is the cause of most audit problems. Use automated tools in your process to allow your developers to focus on the creative parts of the software development.  Keep things as simple as possible.  Drive out risk early.

[Brendan] Where can people go to get more information? Any good online resources out there?

[Bruce] For an executive overview for determining whether a new device is a medical device or for ideas on how to use a static code analysis tool in medical device development, we have a library of whitepapers people can download.

[Brendan] Thanks!

We are starting to see a large amount of Android phones such as the Droid and Xperia X10 (see a review here) and the (soon-to-be-released) first Google phone, Nexus One. With this, expect the number of apps to increase significantly.

Droid vs. iPhone

So with the increased number of apps, do these developers have the right tools to find and fix bugs? Take a look at the leader of phone applications-iPhone. There have been several posts (here and here) that recommend using the Clang static analyzer. Apple has taken it one step further, apparently rejecting iPhone apps that access private APIs. But Clang won’t help you with Java apps.

So what do the Android developers have? Android is just Java, so there are lots of tools, right? Certainly there are static analysis tools, profilers, unit testing tools and many more. But are these tools really taking into account the Android specifics?

Let’s take an example of a resource leak. Resources such as streams, connections and graphic objects must be explicitly closed; otherwise, you run the risk of throwing exceptions depending on the open resource.




For example:

1 static final String propertyFile = "my_config.ini";
2
3 static String getProperyFromConfigFile(String name)throws IOException {
4    Properties prop = new Properties();
5    FileInputStream st = new FileInputStream(propertyFile);
6    prop.load(st);
7    return prop.getProperty(name);
8 }

Here, a resource leak should be identified since line 5 opens up a FileInputStream, but is never closed before exiting the method. Now, this is all well and good and valuable to be found in any Android specific code, but what happens if I’m using built-in classes from the Android SDK?

For example:

1 public boolean onKeyDown(final int keyCode, final KeyEvent event) {
2    if (keyCode == KeyEvent.KEYCODE_DPAD_CENTER) {
3          final MediaPlayer player = MediaPlayer.create(this, ringtoneUri);
4          player.start();
5    }
6    return super.onKeyDown(keyCode, event);
7 }

Here, you have a situation where a MediaPlayer resource is created at line 3, but never closed on exit. Without the knowledge that MediaPlayer is a resource that should be closed, you will miss this type of issue. This extends to many resources and different issues. You can also have Android-specific null pointer exceptions and use of free issues.

Let me know if you’re doing Android development. I want to hear what you are doing to find these kinds of bugs.

Our new documentation wiki is up and running!

For awhile it seemed like we’d never do it. We have a team white board that records our panic level, and for several weeks, the level was up around “hysterical” and “wanting to open my own daycare”.

We also have a white board in front of the doc area, in a hallway where everyone walks by to get to the kitchen.  At one point when we were particularly frustrated with MediaWiki, the topic was “names for the new doc wiki”. A few good suggestions:

the gaping maw, or "the wiki is never done"

And the best one, though we decided it would be unprofessional to make it official:

RTFW

Fortunately, when I was ready to throw in the towel, our IT guy stepped into the ring and beat MediaWiki into submission. He installed extension after extension, found a search engine that worked for us, and configured a great PDF creator. He moved the entire Wiki a few times to improve performance and security. And he was much more tolerant of the state of MediaWiki’s documentation than I was.

So, if you’re a small documentation team thinking of moving to a Wiki, what do you need to make it work?

• Someone outside the doc team needs to handle the technical side, so you still have time to do what you do best: write user documentation. In our case, besides IT, one of our senior developers ended up learning more than he probably wanted to about MediaWiki. He made the wiki the source for context-sensitive help for detected issues; each of these wiki pages allows you to switch from English to Japanese. Some of our users have no access to the internet, so he also wrote a script that exports the wiki to static html for packaging with Klocwork software.
• Read blog entries like Tom Johnson’s Ramping Up on MediaWiki to remind you that you’re doing the right thing.
• When the voices in your head whisper that it’s impossible to both switch your help delivery mechanism and reorganize/rewrite the entire help system in just a few months, take a pill or something.
• When your inner perfectionist rears its ugly head, repeat this mantra: The wiki is never done. The wiki is never done.

In the end, despite feeling like we were being drawn kicking and screaming into the gaping maw of hell, we love our wiki, and we hope our users will too. And users, if you don’t like it, you can change it!