Code Documentation

[Peter Collins <peter -dot- collins -at- BIGFOOT -dot- COM>]

    OK, you've got me sucked in.
1.    Who are you writing for?
2.    What can you assume they know initially?
3.    What are they to know when you are done?
4.    What other motive is there (eg contractual obligation)
    For me, "document the code" is just far to loose. Over the last 40
years I have been inter alia: a programmer, a system designer, a chief
programmer, a user requirements documenter and a technical writer. I could
not document code without a writing plan - though in my earlier days it
would have been a mental one.
    Are you writing for the maintenance programmers who will, years later,
have to delve in to fix some devilish hidden bug? Are you writing for
programmers who will, perhaps years later, use this module as a building
block in their own systems? Would such building block programmers be
in-house or in the public domain?
    Is the code being produced for delivery to a client firm, for wide
public sale, as part of a retail product, to stay in-house, or 'other'?
Does the company producing the code have a product liability for the
performance of the code, or a maintenance contract or obligation internally
or externally to keep it running correctly?
    Is the code written with highly and correctly meaningful names for
variables and labels? Are there comments embedded already? Is the code
appropriately modular, structured, indented, paragraphed with blank lines
or ruler comment lines? Does it follow closely the normal conventions for
clear coding in that language? Does it use deliberately simple structures
or does it contain 'clever' constructs requiring significant subtlety of
understanding? (Any program may be written in either style - the 'clever'
one is usually far far shorter but impossible to understand unless you are
either (a) the author, or (b) in Mensa)
    Is the code self explanatory (with its embedded comments if any) as it
stands, to a programmer skilled in the same language but who has had no
exposure to that project? To such a one, is it clear from reading the code
what each module has to do and why; and how it does it; and what data it
gets in and hands out and how and why?
    I hope I have given you enough clues to help you on your way. If you
need more, just ask, either on or off list.
P
========================================================
Peter Collins, VIVID Management Pty Ltd,
26 Bradleys Head Road, MOSMAN 2088, Australia
+61 2 9968 3308, fax +61 2 9968 3026, mobile +61 (0)18 419 571
Management Consultants and Technical Writers
email: peter -dot- collins -at- bigfoot -dot- com                ICQ#: 10981283
web pages: http://www.angelfire.com/pe/pcollins/
========================================================


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