>     Too bad that 99% of code written more recently is an
>     undocumented pile of crap.
>
> How would you know that?  Today, I'd expect that a good 90% of the code
> written is proprietary and not subject to prying eyes.  A lot of what you
> see as "open source" or public domain is written by ... beginners.

OK, I haven't personally inspected 99% of the code out there, but I can say
that the vast majority of the code I do see is very poorly documented.

I'm mostly a consultant, and occasionally I get called in on a project after
someone else started it.  Most of the time the firmware is in such bad shape
and so poorly documented that it is cheaper to do it right from scratch than
to figure out what the original intent was, document it, find and fix the
bugs, and add whatever features are still left to do.  If the original code
had been written the right way, then this probably wouldn't be necessary.

A good example is going on right now.  We were contacted by a company that
has been trying to design a new industrial product.  Part of the overall
product is a mobile unit that includes solenoids, fluid flow meters, a real
time clock, a keypad, an LCD display, several key switches, an RS-232 link,
an optional cell phone interface, an optional flash memory card interface,
and up to three links to RFID tags and the like.  They told us that the
product was "80% done", and want it finished up.  Apparently they contracted
with another company to design much of the product, and this other company
sub-contracted out the software to some guy who just quit to go to a new
job.  The entire source code they gave me that was supposedly 80% done
consisted of 6,400 lines of C intended to run on a single board computer
embedded in the controller.  There are absolutely no header comments giving
an overall description of what any of the functions were intended to do.
There are a few individual comment lines scattered about the code, but there
are also pages of executable code at a time with no comment in sight.  I ran
a pattern search and found that only 14% of all lines contain any type of
comment.  On inspection, I found that many of those are chunks of code that
have been commented out without any explanation.

I had to tell them the unpleasant news that the software at least is 0%
done, not 80%.  They understand intellectually, but emotionally they have a
hard time abandoning something they claim they spent "a small fortune" on.

Since there is no software investment to protect, and the hardware is a long
way from done too, we are proposing a totally different architecture for the
central controller (there are other architectural problems with the design
that I won't get in to).  This will consist of several distributed smaller
$1 to $10 embedded processors instead of a single $350 single board computer
on a separate board controlling everything directly.  I've given them a
rough verbal outline of what we are proposing, but the real presentation is
tomorrow.

I could site a number of other examples where bad professionally written
code has cost people serious money, but this is long enough already.  Trust
me, these problems are real and I've personally seen them a number of times.

> On the other hand, I WAS duly impressed that you seem to practice what you
> preach, with the code you've kindly made available on your web site being
> very nicely commented...

Thanks.  I really do write all my code that way.  I find that writing good
comments as I write the code is sort of a first pass debugger.  I think that
being forced to explain it to someone else makes you think about it in a
different way which can help point out errors or inconsistancies.


*****************************************************************
Olin Lathrop, embedded systems consultant in Devens Massachusetts
(978) 772-3129, olin@embedinc.com, http://www.embedinc.com

--
http://www.piclist.com hint: The PICList is archived three different
ways.  See http://www.piclist.com/#archives for details.