Re: Code Documentation

Subject: Re: Code Documentation
From: Jason Huntington <JasonH -at- CAPTURA -dot- COM>
Date: Tue, 10 Nov 1998 15:03:22 -0800

Dear Embryos,

<ludicrous advice meant to make a serious point>Start over, writing the
documentation including comments first. </ludicrous advice meant to make
a serious point>

Coding a software solution should come *after*:

1. A description of the real-world problem in plain language.
2. Requirements.
3. Design and architecture.

To be more helpful however, usually code documentation consists of names
and descriptions. In the VB/Java environment you specified, you will
probably want to start by commenting classes, objects, functions, and
routines. After those descriptions are clear, describe the attributes,
variables, properties, methods, subroutines, and events.

The question of where you and the programmers write is mostly a
maintenance issue. However, the literature on Software Development
Process recommends providing documentation outside the code because it's
easier to understand that way.

Code documentation is only a step into the ballroom of process maturity.

You may want to subscribe to magazines such as Software Development
which include lots of advice. In addition to the templates I sent you
earlier, here is a bibliography of some of the Software Development
Process literature:

Booch, Grady. 1996. Object Solutions: Managing the Object-Oriented
Project. Reading, Ms: Addison-Wesley.
Carnegie Melon University, Software Engineering Institute. 1995. The
Capability Maturity Model: Guidelines for Improving the Software
Process. Reading, Massachusetts: Addison Wesley.
Fowler, Martin. 1997. UML Distilled: Applying the Standard Object
Modeling Language. Reading, Ms: Addison Wesley.
Humphrey, Watts S. 1997. Introductin to the Personal Software Process.
Reading, Ms: Addison-Wesley
Kit, Edward. 1995. Software Testing in the Real World. Reading, Ms:
Addison Wesley.
Larman, Craig. 1998. Applying UML and Patterns: An Intorduction to
Object-Oriented Analysis and Design. Upper Saddle River, NJ: Prentice
Hall PTR
Maguire, Steve. 1994. Debugging the Development Process. Redmond, Wa:
Microsoft Press.
McCarthy, Jim. 1995. Dynamics of Software Development. Redmond, Wa:
Microsoft Press.
McConnell, Steve. 1993. Code Complete: A Practical Handbook of Software
Construction. Redmond, Washington: Microsoft Press. Effective techniques
in data processing.
McConnell, Steve. 1996. Rapid Development: Taming Wild Software
Schedules. Redmond, Washington: Microsoft Press. Models of software
Perry, William. 1995. Effective Methods for Software Testing. New York,
NY: John Wiley & Sons.
Wiegers, Karl E. 1996. Creating a Software Engineering Culture. New
York, NY: Dorset House Publishing.
Yourdon, Edward. 1996. Rise & Resurrection of the American Programmer.
Upper Saddel River, NJ: Yourdon Press.
Jason R. Huntington

Senior Technical Writer
Captura Software, Inc.

-----Original Message-----
From: Tracey Moore [SMTP:traceym -at- APPLIEDMAPPING -dot- COM]
Sent: Tuesday, November 03, 1998 11:46 AM
Subject: Code Documentation

My company has recently completed a visual basic/java
application and we =
now need to document the code. (All we've done so far is print
out the =
code itself.) Does anyone out there have experience with this?

How do you document? What should the document look like? Any
suggestions =
on resources for sample documents?

As you can see, we're babies (uh, make that embryos) at doing
this. =
Thanks in advance for your help.

Send commands to listserv -at- listserv -dot- okstate -dot- edu (e.g., SIGNOFF
Search archives at:
Find additional TECHWR-L resources at

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

Previous by Author: Product Requirements Document
Next by Author: What a Tech Writer Really Does (with a tie to We Don't Get No Res pect)
Previous by Thread: FW: Code Documentation
Next by Thread: Re: Code Documentation

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

Sponsored Ads