header files

Subject: header files
From: Goldie G. <goldie3149 -at- hotmail -dot- com>
To: <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 8 Aug 2012 12:49:19 -0700

Hi -

A client of mine does not yet have a product API reference, so users rely heavily on
the explanatory information in the header files. Code comments are separate.

When there is an error in a company's software code, and (after a user
unsuccessfully tries to do something) a result code is returned because of this
error, is it ever okay to indicate in the header file this particular reason for the return
code? If so, how? The code of any software maker contains errors, of course.
This company has suggested that the header could be in the following format:

CannotGetXYZName, "BUG: Cannot get XYZ name"

By contrast, for errors returned when the user makes a mistake, the company
uses the following format -

ReadData, "Error reading data"


ReadData, "Cannot read data"

When the fault is with the company's code itself, what would you do, other than
the BUG: arrangement (except for occasionally addressing problems in the

Thank you.


Create and publish documentation through multiple channels with Doc-To-Help. Choose your authoring formats and get any output you may need.

Try Doc-To-Help, now with MS SharePoint integration, free for 30-days.



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-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives

Previous by Author: Re: Technical Communication Poll: Best Career Prospects
Next by Author: Re: Construction terminology question
Previous by Thread: RE: Update: Data Presentation Architect / Architecture
Next by Thread: TechWhirl: Technical Communication Recap for August 10, 2012

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

Sponsored Ads