From: "Roger Scudder" 

On Sunday, May 02, 2004 at 8:22 PM Bob Stout wrote:

> I regard the project I just finished as a really good example of how
to do such a
> project right.

> The project was a 3-D rotational steering tool (directional drilling
control for oil
> wells). The company had a tool and it mostly worked, but the firmware
was a disaster -
> if you breathed on it, it broke. Worse yet, the fellow who wrote it (I
can't really say
> anyone "designed" it) is an information hoarder who always appears
cooperative while
> providing as little real information as possible.

> Since they wanted it fixed, I started out with an effort improve their
processes and
> procedures. Using software metrics (which no one had ever heard of), I
showed them why
> the code was unreliable. Judged by either lines of code or cyclomatic
complexity, the
> code base was a disaster! The most egregious example was one function
which consisted of
> 2359 lines (1235 code lines) with a complexity of 190. I told them
that most shops using
> complexity metrics require justification for single function
complexities above 7.

Wow! That has got to be a sure sign of an inexperienced programmer (or,
heaven forbid, a really bad one).

To be honest, you just introduced me to complexity metrics as well.  I
found some basic theory at
http://www.sei.cmu.edu/str/descriptions/cyclomatic_body.html#36810 . How do
you go about evaluating raw code modules?  Is there a tool or utility that
you use?

> Next, they expected me to start writing code. Instead, I got everyone
together who knew
> what the existing tool did and what they wanted it to do and we
hammered out a
> functional spec. It was a new experience for them, but they learned
from it that not
> everyone's perceptions and expectations are the same.

I have done dozens of small projects, either for pay or for fun.  I get
really tired of having people expect me to just start writing code. Many
people seem to assume I should just know what they want with minimal
communication from them.  In cases where I am working and need the income,
I sometimes find myself feeling afraid that if I push them to much to get
involved they may throw in the towel and I'll lose the job.  In those cases
I usually just try to give them what I think they want, keeping it simple
and saving time for the inevitable feature creep and change requests.

> With the functional spec complete, I began the design. What I knew,
and they didn't
> figure out until much later, was that the new "firmware" included a
fairly complete
> cooperative multitasking OS. Using an existing off the shelf RTOS
would have been
> problematic. The performance requirements were *very* tight - lots of
FP math (the 68332
> doesn't have an FPU) and the devices we had to use because of the
downhole environment
> (i.e. hot!) limited us to byte-wide memory access. I wasn't sure that
the overhead of an
> existing RTOS would work, so I didn't push for it.

Whoa!  I'm not worthy!  Seriously..  I'm not worthy!  :-)

I'm basically an application/utility writer, with no experience working
down to the metal like you do.  I would love to get into it though.  I'm a
PA certified Tool & Die Maker, but I've given up the trade to work in
IT.  I have a pipe dream that involves turning my garage into a machine
shop and delving deep into robotics.

> As I mentioned before, the other programmer assigned to work with me
on it initially
> didn't believe any of the design would work. I knew it would because
I'd used a lots of
> similar code several years ago writing modem firmware for Compaq, also
using a 68332.

Nonbeliever, huh?  Well, if anyone could give em' religion, it's you.
;-)

> To make a long story short, I finished up this past week. Overall, our
schedule
> performance exceeded expectations. There was grumbling at first
because they didn't

Congratulations on a job well done!

> Aside from this specific success story, now all the other firmware
groups there are
> making use of the version control system and the management has a new
respect for the
> use of formal specification as well as doing real design rather than
hacking code
> together. When I arrived, all their firmware development activities
were at CMM level 1.
> Now they're mostly between levels 3 and 4, with my project a solid 4.
What they'll do in
> the future, I can't say. But at least they now know there's a better
way than what they
> did before.

Hey, thanks for sharing your experience on this project. It gave me some
things to thinks about.  I'm definitely doing to dig deeper into complexity
metrics.  It sounds like a good way to evaluate unfamiliar code.

-Roger

--- BBBS/LiI v4.01 Flag-5