TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Nice up my .H file From:Dan Azlin <dazlin -at- SHORE -dot- NET> Date:Mon, 3 Feb 1997 22:31:10 -0500
At 13:00 2-3-97 EST5EDT, Dennis Carothers wrote:
>I've been asked to format a programmer's header file to make it look
>a bit more "professional." Following is a sample:
>
<snip>
>
>I'm not sure how much I can, or should, edit this.
>Can someone point me to a standard for this type of writing?
>
>Thanks,
>
>Dennis Carothers
>dcarothers -at- bgs -dot- com
>
Dennis,
Coding is a very personal activity for most programmers, and one very much
in need of standardization if a given programmer's work is every going to
make sense to anyone else who has to use the original code. Bravo to
whomever made this request.
There are two sources that you might look for (amid several other, no doubt):
Professional Software Volume II, Programming Practice, by Henry Ledgard
with John Tauer, ISBN 0-201-12232-4. You should probably look for this one
in a university library as it is about 10 years old. But it covers many of
the issues of standardized formatting of source code in order to achieve
self-documenting source files.
Either of Steve Maguire's books from Microsoft Press (Writing Solid Code;
Debugging the Development Process) should give you some insights,
especially the latter book.
In any case, the goal is to have the source file be documented in such a
way that any programmer could pick up the file for the first time and see a
full explaination of the file's intended purpose, development environment,
development history, functional description, requirements, etc. Consistant
header formatting makes much of this information available on page 1. Keep
in mind that different programming languages and development environments
may have different requirements for inserting comments. However, they all
give you the ability to add as much text as you want to the file without
causing any functional problems.
The ordering of code within the source file is something that used to be
rather rigidly defined (part of what we called good programming practice,
or structured programming), but OO programming has created a new kind of
spagetti code.
Maybe this is more than you were looking for, so I shut up. Check out
Ledgard's book if you can find it.
Good Luck.
- Dan Azlin
Dan Azlin ** WORD ENGINEERS, Technical Writing & Publishing **
dazlin -at- shore -dot- net 7 Myrtle Street
ph/fax 508-921-8908 Beverly, MA 01915-3315
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
