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

Subject: Checking code (was: Software engineer tech. writers? )
From: "Sandy Harris" <sandyinchina -at- gmail -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Mon, 3 Sep 2007 00:46:09 -0700

On 9/2/07, Dossy Shiobara <dossy -at- panoptic -dot- com> wrote:

> Are there software-oriented tech. writers who are also software
> engineers who can read through C source and write documentation
> based on what it does?

How many writers analyse the code they document?

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.

Results I recall:

Under 15% of "switch" statements had a "default" case.

The "assert" macro was used about 5 times in several thousand lines
by one programmer, not at all by any of the others.

The C idiom for checking return value of functions that allocate resources,
fopen(), malloc(), fork(), etc. is something like

if( (fp = fopen(...)) == NULL)

This was rarely used. In most cases, there was no test in following
lines either.

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.

Sandy Harris,
Nanjing, China

Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more.

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity!

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.


Previous by Author: Re: Software engineer tech. writers? Do they exist?
Next by Author: Re: 'Step Up to Leader' Post > Tangential Question
Previous by Thread: Re: It happens to all of us . . .
Next by Thread: Checking code (was: Software engineer tech. writers? )

What this post helpful? Share it with friends and colleagues:

Sponsored Ads