Checking code (was: Software engineer tech. writers? )

[Geoff Hart]

Sandy Harris reports: <<At one point I had access to 600,000 or so  
lines of a client's C code, so I wrote a few little grep scripts to  
test it a bit. Results were appalling. It was production code, but  
only used as internal test tools; it wasn't what they shipped to  
customers.>>

Apalling doesn't surprise me. I don't get the impression that the  
people who teach programming courses spend enough time on quality  
assurance, or that the people who employ the programmers care enough  
to give them the time to do the job right. I may be doing the  
teachers an injustice, but the results speak for themselves: anyone  
who uses modern software is all too familiar with shoddy coding.

C strikes me as an example of language or compiler designers being  
far too clever for their own good, and insufficiently concerned with  
the real-world conditions under which software is created and used.  
I'm way out of date on this, so please correct me if I'm wrong, but  
one of the big flaws in C is that it doesn't have "automatic garbage  
collection" (originally billed as one of the huge advantages of  
Java), and this was one reason why so many C programs developed fatal  
memory leaks. In any event, many memory leaks are simple human error:  
failing to deallocate memory when you allocate it. That's about as  
smart as writing an interative loop without remembering to add the  
terminator (e.g., FOR without NEXT, DO without UNTIL).

C'mon, guys: isn't this why we invented computers (to automate things  
that humans can't be relied upon to do right)?

<<If you do check code this way, what should you do with your  
results? I considered passing them on to the programming manager, but  
did not do it. I figured as a contractor and "only" a tech writer, it  
was not a good idea to stir things up that way.>>

You should reconsider that approach. First, if those of us who are  
aware of problems don't speak up, those problems go unsolved.  
Sometimes the consequences are trivial, sometimes they're major and  
potentially fatal. The problem with lazy programming is that it  
becomes a habit, and that habit leaks into the production code. When  
it does... I've seen this happen with editors, so I can only imagine  
it happens worse with programmers faced with insane deadlines.

Second, pointing out problems is one of the best ways for us to earn  
respect from our colleagues. The trick, of course, is to reveal the  
problems in a helpful way, not in an "I'm smarter than you and you  
should be fired" way. (That is, unlike the way I've described  
programmers above. Sorry for the rant!) That's doubly true in China,  
where mianzi enters into the problem: you can't risk making someone  
look foolish in public. Even so, I've certainly heard tales of even  
careful bearers of bad news being punished instead of rewarded.

Instead, it may be worth your while talking to the specific  
programmers who created the problem (if you can identify them) or to  
each programmer individually, if you can make the time. Then, the  
goal becomes one of making them look good (i.e., improving their  
mianzi) at the next performance appraisal. For example, what if you  
offered them your grep code or a customized version of it so that  
they could find such problems themselves simply by running the code?  
I've done similar things with authors by writing performance-support  
tools to help them find recurring problems in their writing before  
anyone else ever sees the problem.

Is this just empty theory, or does it actually work? Can't say for  
programmers as a group. I do know firsthand that it works great with  
most of my 95 Chinese clients and a couple hundred Japanese clients  
(all researchers at major universities), and worked well with the two  
programmers at my last job. That's only one data point (me) that I  
hope others can expand upon.


----------------------------------------------------
-- Geoff Hart
ghart at videotron.ca / geoffhart at mac.com
www.geoff-hart.com
--------------------------------------------------
***Now available***  _Effective onscreen editing_
(http://www.geoff-hart.com/home/onscreen-book.htm)