Browse Prior Art Database

Maintain Design and Program Source Together as One Entity

IP.com Disclosure Number: IPCOM000115014D
Original Publication Date: 1995-Mar-01
Included in the Prior Art Database: 2005-Mar-30
Document File: 8 page(s) / 271K

Publishing Venue

IBM

Related People

Pramberger, J: AUTHOR

Abstract

It is very common when writing code in any programming language that the design and documentation that belongs to this code is written and maintained in separate source files.

This text was extracted from an ASCII text file.
This is the abbreviated version, containing approximately 29% of the total text.

Maintain Design and Program Source Together as One Entity

      It is very common when writing code in any programming language
that the design and documentation that belongs to this code is
written and maintained in separate source files.

      The effect is that design and documentation must be manually
mapped to written code and/or transferred in code by rewriting pseudo
code, comments, etc.  Also, if updates are made to the documentation
and/or the code it must be manually cross checked and updated in both
directions.  Both entities are treated separately without a physical
link between the materials (source code, documentation).

      If styles and views changes to present the created material a
rewrite must be done to achieve the detailed view or visual
appearance and still make sure that related sections still map.  This
means that true functions (source code) still maps to functions
descriptions on several levels.

      Most of the times after one iteration of design, let's say the
code is written and tested, the design gets never updated again and
is lost.  Very often discrepancies between source code and
documentation
will be found by accident like a needle in the hay stack.

      In other cases designs are never written because it is too much
effort to write design information after coding (i.e., after
prototyping) in a separate file which contains a lot of redundant
information and it is hard to match the sections in design to the
relevant coding sections.

      To overcome the described problem related information must be
maintained easily in one source or have physical links if maintained
in different sources.

      To achieve this, the commentary sections of source code will
contain different level of information, marked by extending the
comment delimiters by user defined characters (for an example see
Fig. 1) A utility program will then be used to parse out the needed
sections from the source code to produce the relevant documentation
(Fig. 2).

      Such documentation may range from just code to higher level
information in one source.  It may even contain information which
goes to external user documentation.  It is also possible that a set
of sources and documents do intersect which each other by imbeds and
includes.

      With this technique information on different levels and on
different topics are brought physically together where they should
be.  Only with this physical connection an easy mapping of those
information sections for consistency and avoid redundant information
can be achieved.

      The kind of delimiters associated to the commentaries are
defined either by default or by user to the Source Translator
depending on the source code type (Fig. 1).

Different kind of section could be for example:
  o  End User documentation sections
  o  Specification information
  o  Design Information
  o  Just the source code.  (Not really necessary, because the...