From: Bob Stout 

On Tue, 4 May 2004, Roger Scudder wrote:

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

Software is the only engineering discipline where the product directly
reflects the engineer's thought processes. In this case, the fellow who
wrote this is afflicted with totally chaotic mental processes. The thing
that keeps him around there is that he's very good with numerics.

> 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?

One of the secret weapons in my bag-o-tricks is a tool called C-DOC from
Software Blacksmiths http://www.swbs.com/>. It's a comprehensive
C/C++ code analysis and documentation tool. In addition to called/used
lists, function trees, pretty printing etc., it also includes a complexity
metric. A particularly nice feature for consultants like me is that the
standard version only costs $125 and the pro version (which includes Java
and more comprehensive C++ support) is only $215.

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

A key part of any such project is educating your employer/client/customer.

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

Sometimes that's all you can do. Even then, though, I try to write up
something that captures what they want at a very high level and give them a
chance to object. Often, it's all that's needed to trigger a more complete
process. But even when it's not, at least you have a starting point that
you can return to.

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

I started out in hardware and have always remained pretty close to the
"bare metal". I'm a lot more comfortable writing device drivers
and interrupt service routines than dealing with the level of abstraction
typical of most of today's popular applications development environments.
Besides, it's more fun to me to see that the code is working because you
can see valves and motors operating, data acquisition taking place, etc.
than to just see something pretty on a graphics screen.

> Congratulations on a job well done!

Thanks... To be honest, I've been so immersed in it these past 9 months
that it wasn't until the job was suddenly complete that I took the time to
be impressed with what we'd accomplished. The reason the job was
"suddenly complete" is that we were seeing such short maintenance
turn-around cycles with the new code that TPTB realized that the job they'd
hired me for was actually done. They're getting ready to go into the 2nd
set of field trials, but are confident that any changes they might want can
be quickly and reliably implemented by the staff programmer I had working
on it with me.

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

I can't recommend C-COD highly enough. It's one of those tools that you
don't need too often, but when you do, it's invaluable. Still the cost is
so reasonable that it's easy to justify and can pay for itself the first
time you use it. Even if you don't need the complexity metric, the tools
for documenting which variables are where, and which functions call (and
are called by) other functions can ease the nightmare of digging into
existing code.

Another major use is for dealing with management.  In this case, that I
first went in with C-DOC and positively documented how bad the existing
code was paid huge dividends. First of all, they had never heard of
software quality analysis tools and so wondered how come their own staff
wasn't aware of them. Second, I simply took the numbers and a couple of
standard reference books on software quality and showed them how industry
standards compared to their performance. In one fell swoop, I had performed
a valuable educational service and cut any opposition to my re-design off
at the knees! ]:> It also gave me a starting point for implementing a
set of coding standards.

-------------------------------------------------------------
Consulting: http://www.MicroFirm.biz/ Web graphics development:
http://Image-Magicians.com/ Software archives:
http://snippets.snippets.org/
  c.snippets.org/   cpp.snippets.org/      java.snippets.org/
  d.snippets.org/   python.snippets.org/   perl.snippets.org/
  dos.snippets.org/ embedded.snippets.org/ apps.snippets.org/
Audio and loudspeaker design:
  http://LDSG.snippets.org/   http://www.diyspeakers.net/

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