Code Documentation

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

    Steven is right, and I am keeping a copy of his excellently structured
advice as part of my professional toolkit - thank you Steven.
    In case non-programmers are wondering why -
   "Changes should be noted in comments at the point the code is
changed, including a date/time stamp, and in a master list of changes
at the beginning of the main object (with pointers to the location
in the code where the change was made)."
    Before I explain this, I would add that the change documentation should
also include the document number of the authorising document and the reason
for the change, (bug fixes - the nature of the symptom and if the problem
was complex an explanation of how it came about that it all hit the fan;
for user requests a brief description of the change from the user
perspective and why it was implemented this way; for system enhancements
the reason that management decided to adopt it). Many grey-haired
professional programmers believe that any code rendered obsolete by the
change should not be deleted but rather turned into comments annotated with
the date or the change number of their withdrawal.
    Program maintenance is MUCH harder than program design and development.
That's because the maintainer has to deal with the things that were
forgotten by or were too hard for the original builders (to over-simplify
that issue out of all recognition). You may come along ten years after the
first code was set running (I am NOT kidding) to deal with bug number 3193
(seriously) in release 217 (however it may be numbered - V3.14 perhaps). It
genuinely helps to know all the things that Steven et al have told us of.
It also helps to have someone on hand who can say - "oh yes, five years ago
we had to take out the look-up via address-id because of a bug in the
database handler - never did find out what was behind that, but it fixed
the problem". Of course, fat chance you will have that sort of help, but
notes to that effect, and the old code that was cut out, all sitting there,
will save you the catastrophe of [once more]adding an address look-up for
some new client or manager, ignorant of the pandora's box that may still be
lurking there to bite you.
    Large (and smart small) programming shops have a (program-literate)
librarian who does a source code file compare on each maintenance task to
eyeball every line changed and confirm it is relevant and appropriate to
the change request. The change coding techniques I describe should sit well
in that environment.
    In addition, including the change number at least once in each section
of changed code will allow easy searching for all places where that request
caused program amendments. When a given change is suspect (we all know how
some parts of Word got worse as MS fixed the problems up) it helps to be
able to find all its bits at once, and then to be able to follow the
logic(!) of the programmer who made the 'fix'.
    Very many large (millions of lines) commercial systems have huge chunks
of code in them that go back years. I am sure that some major commercial
systems in use today contain material that was written thirty years ago.
    I was personally involved in the death of a major organisation whose
systems had been designed thrity years previously by the senior users (now
long retired and mostly dead) written in assembler, poorly documented,
modified every month by a series of programmers (average stay - two
years) - and now the hardware was long obsolete, parts unavailable,
engineers no longer trained for it - a dodo.
    A whole new computer had to be programmed for the new computer and be
able to accept ongoing business changes. It could not be done. The
knowledge that built the system was gone. Humans did not need to know any
more - the computer did it. The design documents (if any) had long been
lost. The assembler program suite WAS converted, semi-mechanically, from
the old machine to the new, but the result was not maintainable (due to
lack of explanations), though it did run well enough to keep the old books
while the firm was wound down. A whole new company had to be set up to
service the client base, starting from scratch, with new computer programs
designed from the ground up, and based on a new and greatly simplified
business rules. I do hope they don't now lose THEIR program documentation.
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=