Re: Nice up my .H file

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


Previous by Author: Re: White space in manuals
Next by Author: Re: Contracting moral dilemma
Previous by Thread: Nice up my .H file
Next by Thread: Re: Assumption of Civilized Society


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

Sponsored Ads


Sponsored Ads