Re: Advice needed on "Include" files

[Linda Sherman <linsherm -at- GTE -dot- NET>]

Thomas Quine wrote:
>
> Many programming languages use "include" files. Include files are a sort of
> sub-file that gets called by a source program from within its own code -
> i.e., it gets "included."
> At my workplace, these files are called "includes". Seems wrong to me. But
> I have to document them for other programmers, so I need some advice.
> Has anyone had experience writing about these sorts of files? What do you
> call them?

It depends on the language and, in some cases, the type of file.

In Pascal, for example, the term is "unit". Other languages have other
terms. I suspect, however, that since your staff is using "includes",
they are programming in a language where "include file" is the standard
accepted term.

In C and C++, the term "include files" would be understood. However,
"header files" /*might*/ be better. I say "might", because although it's
extremely rare to find an include file that is not a header file, the
possibility exists. If I were writing about C or C++ code, and if the
file IS a header file, I would use "header" or "header file" rather than
"include file", because it's more specific. But be careful not to use it
for include files that aren't actually headers.

As your audience is programmers, you will probably do best to stick with
standard geekspeak, even if it sounds like cant or poor English to you.
I say this as a former programmer who has seen documents where
non-programmers have tried to de-cant or re-invent the terminology. The
results are annoying at best, and often confusing or ambiguous.

L.
--
Linda K. Sherman <linsherm -at- gte -dot- net>
Freelance Writer: Technical - Business - Government

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=