Software Documentation Revolution - WorldComp Proceedingsworldcomp-proceedings.com/proc/p2012/SER6083.pdf · 2014-01-19 · documentation from source code. 4. Documentation in NSE

NSE Dynamic Software Documentation - Software Documentation Revolution Based on Complexity Science

Liana Ye 1, Lin Li

2

1PeaceNames.com, USA

2NSESoftware, LLC, USA

Abstract

This paper introduces Nonlinear Software Engineering

(NSE) Documentation Paradigm based on complexity

science. By making software documents automatic,

graphical, colorful, traceable, virtual, maintainable, and

always consistent with source code dynamically, NSE brings

revolutionary changes to software documentation.

Keywords: software documentation, software document,

visualization, diagram, testing, maintenance

1. Introduction

eHow contributor O Paul pointed out that software

documentation pervades the software life cycle. It is the

visible part of the software process. Without it, software

cannot be maintained, users are hard to train and the

software is virtually unusable. Without it, new developers

would have to re-invent the wheel in software development.

Software documentation is the most important manifestation

of software. It is the guide through the software maze [1].

Experience has shown that technical software

documentation is unsatisfactorily maintained. The

implications of outdated documentation are costly and can

damage businesses (http://www.sig.eu/en/Services/DocGen).

Software documentation has been created manually with

"cut and paste", or generated by a semi-automated tool for a

large software product. Often the documents obtained with

current software documentation techniques and tools are

* not traceable,

* not accurate,

* not precise, and

* not consistent with the source code, and

* cannot be holistic.

This paper discusses a source code based software

documentation approach based on complexity science

solving all of the problems listed above efficiently, and

bringing revolutionary changes to software documentations.

2. What Does a Revolution in Software

Documentation Mean? According to “The Structure of Scientific Revolutions”

[2], a revolution in software documentation means:

(1) Bringing drastic, complete, and fundamental change to

the software documentation paradigm

(2) Resolving some outstanding and generally recognized

problems in software documentation;

(3) There is no other way to efficiently resolve those

outstanding and generally recognized problems in

software documentation.

3. Documentation Paradigms

Documentation is a software production process,

reflecting multiple levels of decision-making by people,

especially software engineers. Fig.1 shows the mapping

from requirements to source code production cycles in

waterfall model on a reductionism base.

Fig.1. Three-dimensional software production cycles need

documentation

Documentation is required for software development in the

large arrow direction, where engineers are focused on

coding and maintenance. Unconnected words indicate

standardization efforts and numerous internal debates about

software development.

3.1. Software documentation revolution condition (1)

NSE software documentation paradigm brings drastic,

complete, and fundamental change to the software

documentation paradigm by paradigm shift of the

foundation of software documentation from the

reductionism base of Fig 1, which is manually and partially

traced, and its marketing, design and coding documents and

specifications are strongly top-down typed and hard to

change. NSE is a complexity science based, innovative

framework FDS shown in Fig. 1’.

Fig. 1’. FDS (Five-Dimensional Structure Synthesis

method) framework

3.2. Software documentation revolution condition (2):

The outstanding and generally recognized problems in

software documentation are characterized by:

(a) Reductionism and superposition principle: the whole of a

complex system is the sum of its components, and almost all

tasks and activities in software documentation are

performed linearly, partially and locally.

(b) Linear process models: where workflow goes linearly in

one direction with only one track without counting upstream

movement. It requires software developers to always

document their software with no errors and no wrong

decisions.

(c) Constructive holism: the components of a complex

system are completed first, then the system as a whole is

assembled from its components.

(d) Impossible to be holistic: many small pieces of

documents are generated with no automated summation of

the entire system, missing the big picture of the software

product. Even if some tools can be used to document an

entire software product, short of automated and self-

maintainable traceability, its system level graphical

documentation contain too many connection lines as shown

in Fig. 2, making the documents hard to understand and

almost useless.

Fig. 2 A traditional call graph without traceability. Source:

http://keithcu.com/bookimages/wordpress_html_m1e9af381.jpg

(e) Graphic documents and source code are separated

making it hard to keep them consistent, especially after

product modification.

(f) Documents are generally not traceable.

(g) Documents obtained are stored statically as images in

Postscript, XML, or other formats, requiring huge

amounts of space and long loading times.

(h) Manually or graphic editor created graphic documents

are not automatically generated, time-consuming to draw,

hard to change, and hard to maintain.

(i) Documentation is error prone and may not be accurate.

(j) The obtained documents are not precise. They can not

directly and graphically show whether a code branch or

condition combination has been tested or not.

3.3 Solution from NSE software documentation

(a) Based on complexity science, particularly the

nonlinearity principle and the holism principle, all software

documentation tasks and activities are performed

holistically and globally, as shown in Fig. 3.

Fig. 3 An example in NSE documentation on a complex

software holistically

(b) Nonlinear process model: Workflow goes nonlinearly

through two-way interaction with multiple tracks,

supporting both upstream and downstream movement as

shown in Fig. 1.

(c) Generative holism: The whole of a complex system

comes first in embryonic form. It grows up with its

components.

(d) Holistic: Documents for an entire software product are

automatically generated to make it easy to view the

documents and understand internal connections, as shown in

Fig. 4.

Fig. 4 An application example for NSE to trace a module

and all its related modules upstream and downstream.

(e) Source code (either a stub program or a functional

program) is the source for most graphical document

generation. The graphic document is the visual face of the

corresponding source code. They are always consistent with

each other.

(f) Documents are traceable to and from the source code.

Fig. 5 Static visibility example – Forward tracing a test case

to view which modules can be tested

(g) Documents are consistent with their source code after

product modification with updates to database:

Fig. 6 Requirement Changes: Defect Prevention using

forward tracing through the related test cases to determine

which modules should be modified for a requirement

change.

(h) Documents are dynamically generated directly from the

source code. Corresponding databases are virtual without

images in memory or on hard disk (with user option to print)

to greatly save space and make the speed of display about

1000 times faster than established practice.

(i) Generated graphical documents are accurate to the code.

(j) Generated graphical documents are precise. They can

directly and graphically show whether a code branch or

condition combination has been tested or not.

NSE software documentation supports the entire software

development process, from requirement development

through software maintenance.

3.4. Software revolution condition (3): No other method

can efficiently resolve those outstanding and generally

recognized problems in software documentation except

generating documents automatically from source code.

Although there are many software documentation tools

available on the market, they are disjoint tool sets. Alistair

Cockburn, characterizing people as non-linear, first-order

components in software, development: “We methodologists

and process designers have been designing complex systems

without characterizing the active components of our systems,

known to be highly non-linear and variable (people).” http://alistair.cockburn.us/

From source code to generated documents, NSE produces

automatically generated documentation from source code,

displays coded decisions made by people keeping bi-

directional traces for every symbolic connection in the

system, updates function call statements or testing

conditions dynamically with graphical representation for

highly non-linear and variable people, with precise

quantitative information about how many requirements may

be affected and how many function call statements may

need to be modified. We see no other way to efficiently

resolve previously mentioned outstanding and generally

recognized problems but to take automatically generated

documentation from source code.

4. Documentation in NSE is Dynamic

Source code is the ultimate software system

documentation. Complete graphical relationship

representation of each component is determined when the

source code is compiled. NSE collects all information on

the software system, then generates holistic, graphical,

interactive, and traceable documents automatically,

including a stub program meeting development and product

specifications and a functioning program for forward

engineering or reverse engineering.

Fig. 7 Traceability among all related documents, test cases,

and source code

As shown in Fig. 7, source code is the source for

automatically generating graphic design documents, while

those graphic design documents become visual faces of

source code. The design becomes pre-coding, and coding

becomes further design. The graphical documents are

traceable for static review and executable for dynamic

defect removal, as shown in Fig. 4.

Self-maintainable documentation facility is established

through dynamic traceability among design documents, test

cases and the source code, as shown in Fig. 7. After the

source code is altered following a requirement change, the

design documents and modified source code are

automatically incrementally updated, facilitating defect

prevention, as shown in Fig. 6.

4.1. Workflow in NSE Documentation Paradigm

Workflow for NSE software documentation paradigm

consists of source code of regular programs and stub code of

design documents:

Fig. 8 The workflow of NSE documentation paradigm

The objectives of NSE documentation paradigm are:

(a) combining software programming and graphical

software documentation seamlessly;

(b) making one source for both human understanding and

computer “understanding” - through static review by people

of the graphical documents and dynamic program execution

to ensure the upstream quality of a software product.

(c) realizing all kinds of documents (both manually drawn

and generated by third party tools) traceable to source code

to keep them consistent with each other through the

established transparent-box method, combining functional

testing and structural testing together seamlessly with the

capability of establishing bidirectional traceability.

(d) generating most software documents automatically, as

much as possible.

(e) making software documents visible, as much as possible.

(f) making a software product truly maintainable and

adaptive to the changed or changing environment.

4.2. NSE software visualization notations

A majority of NSE documentation paradigm is

visualization in 3J (J-Chart, J-Diagram, and J-Flow diagram)

graphics. For example, Classes, using HAETVE model, are

represented in several graphical notations: J-chart,

ActionPlus Diagram, J-flow and J-Diagram as shown in Fig.

9.

Fig. 9 NSE Graphical representation for a class

Time-Event table documents testing events Time-event tables are written in the comment part of a stub

program or regular program. An example is listed below:

/* Time-Event table:

...

*/

4.3. J-Diagram documents message sending & receiving Graphically representing massage sending and receiving in

the automatically established “click-to-jump” facility as

shown in Fig. 10.

Fig. 10 Click-to-jump facility automatically established for

showing message sending and receiving.

4.4. Software product is visible in multiple views

(a) Static view of the cyclomatic complexity of a program.

Fig. 11 An example of Cyclomatic complexity analysis

(b) Dynamic view of a program

Fig. 12 An example of performance analysis

4.5. From macro to micro with MC/DC test coverage

(a) Holistic analysis for an entire product, Fig 13:

Fig. 13 Holistic MC/DC (Modified Condition/Decision

Coverage) test coverage analysis

(b) Detailed MC/DC test coverage analysis for an individual

class or function, Fig. 14.

Fig. 14 An application example of detailed test coverage

analysis of a module

4.6. From procedure to data

(a) Function cross-reference analysis, Fig. 15.

Fig. 15 an example of function cross-reference analysis

(b) Data analysis, Fig. 16.

Fig. 16 An application example of variable analysis

4.7. From System level to file level to statement level

(a) System-level version comparison, Fig. 17.

Fig. 17 An example of holistic version comparison at system level.

(b) File-level version comparison, Fig. 18.

Fig. 18 An example of file-level version comparison

(c) Statement version comparison, Fig. 19.

Fig. 19 An example of statement version comparison

4.8. Dynamic visibility: Tracing a test case not only to find

what modules can be tested, but also to directly play the

captured test operations back through the batch file (.bat)

specified in the @BAT@ keyword within the test case

description part – see Fig. 20.

Fig. 20 Dynamic visibility – tracing a test case to play the

captured operations back

4.9. Interactively traceable

With NSE the generated documents are interactive – for

instance, the user can click on a module-box to use that

module as a root to generate a sub-call-graph, Fig. 21.

Fig. 21. Interaction example: click on a module-box to

generate an isolated sub-call-graph

Most of the generated documents are traceable, Fig. 22.

Fig. 22 Tracing a module to see all the related modules

4.10. Linkable and convertible

With NSE, different graphical documents can be linked

together - see Fig. 23. Generated logic diagrams can be

converted to control flow diagrams – see Fig. 24.

Fig. 23 An application example - linking a call graph to the logic

diagram

Fig. 24 An example of diagram conversion from a logic

diagram to control flow diagram

4.11. Local documentation to Internet

With NSE, many static and dynamic analysis reports can be

automatically generated as in Fig. 25.

Fig. 25 An application example of static and dynamic

program analysis and reporting

Generated reports for static and dynamic program analysis

can be saved in HTML format to be used as web pages, Fig.

26.

Fig. 26 Code analysis reports saved in HTML format to be

used as web pages

4.12. Preventing requirement conflicts: Perform backward

tracing to the modified modules (in this example, two

requirements are related), Fig. 28

4.13. Project management: Through keywords used in

testing traced back to project management view, Fig. 29

5. Major Features of NSE Documentation

Paradigm The graphical documents generated by NSE

documentation paradigm are:

Holistic – NSE documentation paradigm generates

holistic charts and diagrams to document an entire software

product.

Interactive – the generated graphical documents are

interactive, the generated charts/diagrams themselves are

also the interfaces to accept user’s commands.

Traceable – with NSE most of the generated documents

are traceable, useful for validation, verification, and semi-

automated inspection and walk through,

Accurate – Source code to NSE, including a stub

program, is also the source to automatically generate most

graphical documents, so that the generated documents are

accurate and consistent with the source code.

Precise – the generated graphical documents are precise,

and the corresponding documents can show how many

times a branch is executed, and what code branches and

conditions have not been executed.

Virtual – with NSE, most graphical documents are

dynamically generated from source code, so there is no need

to save their hard copy images in memory or disk, so that a

huge amount of space can be saved. The display speed is

about 1000 times faster compared with established practice

under comparable and similar operational environment. The

generated holistic charts and diagrams are shown within one

window, no more and no less. When scrolling occurs, the

new portion of the chart will be generated dynamically.

From a users’ point of view, there is no difference between

virtual charts and the regular charts occupying a huge

amount of space in computer memory.

Massive – the graphical documents are generally about

100 times the size in disk space of their source code. It can

be automatically generated at system-level, file-level, and

module-level. For each class or function, NSE

documentation paradigm automatically generates the logic

diagram shown in J-Diagram notation with untested

branches and untested conditions highlighted, control flow

diagram shown in J-Flow diagram notations, quality

measurement result shown in Kiviat diagram, etc. The

graphic display capability is massive.

6. Application NSE documentation paradigm has been commercially

available and supported by Panorama++. All screenshots

shown in this paper come from real application examples.

7. Conclusions The established software documentation paradigm

based on reductionism and superposition is outdated. NSE

software documentation paradigm resolves the outstanding

and generally recognized problems in software

documentation, and causes a paradigm shift to complexity

science based principles, making the whole of a complex

system greater than the sum of its components. The

characteristics and behaviors of the whole emerge from

interaction of its components.

Source code is not the best documentation of a

software product, but source code is the best source to

directly and automatically generate holistic, interactive,

traceable, consistent, accurate, precise, massive, and

graphical documentations for the software concerned.

There is no way to solve the problem of inconsistency in

documentation except to generate documentation directly

from source code. Panaroma++ demonstrates the feasibility

of such an approach, turning software reverse engineering

into a software documentation revolution.

8. References [1] (http://www.ehow.com/about_6706857_importance-

software-documentation.html).

[2] Kuhn T (1962) The structure of scientific revolutions.

The University of Chicago Press, Chicago