Welcome to Atalasoft Community Sign in | Help

Whiteboard Engineering

Like many software engineers, I'm a visual thinker--so much so that I often find it challenging to talk about an algorithm or design without drawing pictures.  I depend on whiteboards (or their analog) and to that end, I insisted on having several in installed in our conference room.

One thing that I see with the whiteboards is this: a hapless person picks up a pen, starts writing and gets light streaks or nothing at all.  Usually, the person recaps the pen and picks up another.

This is a fundamental user interface problem with whiteboard pens: there is no way to tell whether or not they've reached the end of their useful life just by looking at them.  Chalk does not share this problem - you can tell by looking at chalk if it needs to be replaced.  I hate the human reaction to a pen that's out.  I imagine that the reasoning is, "my task is to write something on the board, not to do pen maintenance, therefore I will work around the empty pen."  I hate this.  Hate, hate, hate.  All it does is perpetuate an existing problem to the next poor shmoe who picks up the empty pen(s).

If I encounter a dry pen, I throw it away immediately.  It takes about the same amount of time as putting back a useless pen and makes it better for you and for the next person as well.

As a component vendor (and consumer), I encounter something like this all the time.  In writing or debugging code, I will stumble across an interface or a design that could've been done better or a bug in the code.  I can recap the pen by ignoring the problem or by writing a work around, or by re-implementing the same boiler plate code to an unstreamlined interface.  This is not the right thing.

Instead, the right thing to do is to fix the problem.  After all, I don't want our customers to find these problems.  There's a little more to it, though.  Fixing one of these problems isn't always as simple as changing the code.  In reality, what should happen is something like this:

  1. Write a unit test that fails, tripping this bug
  2. Create a bug report and get it into your database
  3. Assign the bug to the right person, with the right priority
  4. If the bug is yours, assess the potential fallout of applying your fix
  5. Fix it, and note the fix in the source code
  6. Re-run the unit test and all related unit tests to verify the fix
  7. Release note the fix
Steps 3 and 4 are the things that makes this substantially different from recapping the pen and throwing it out.  If it's not your code, your fix might create new problems because you don't understand the repercussions.  Your fix may create breaking interface changes.  Your fix might be much lower priority than other work.  Including all of these steps reduces the chances that a quick, convenient fix will lead to more damage by formalizing the assessment and by creating an audit trail in your bug database and in your code.

One step further than this is that if you find one bad pen, to find any others that are bad and replace them too.  The same thing applies with engineering, but is often even harder.  At the time that you find and verify one bug, ask if that particular bug could manifest in other places in your code or if that class of bug could be in other places and start searching.  This might lead to major refactoring or a lot of time spent searching, but the investment is worth it in most circumstances.  You get better quality code, a greater familiarity with your code, and more confidence in what you produce.
Published Monday, May 21, 2007 8:01 PM by Steve Hawley

Comments

Wednesday, May 23, 2007 5:37 PM by MrPedantic

# re: Whiteboard Engineering

Good post, as usual.

Likewise, if you have a CRM system and a customer reports a bug, or if tech support or QA find an issue, the process should be *exactly* the same.

I don't agree about noting the fix in the source code, though: that's what the version control system is for, provided it's integrated with the defect tracking system so you can easily see what changed for a given issue.

I'm more and more convinced that not only is the code the design, but comments should be used as little as possible (but no more): it's hard enough to maintain code, and it's even harder to maintain comments.

Anonymous comments are disabled