July 11 th, 2005 Software Engineering with Reusable Components RiSE’s Seminars Sametinger’s book :: Chapters 16, 17 and 18 Fred Durão.

July 11th, 2005

Software Engineeringwith Reusable Components

RiSE’s SeminarsSametinger’s book :: Chapters 16, 17 and 18

Fred Durão

July 11th, 2005 2

Summary Software Documentation (Chapter 16)

Documentation Categories User Documentation Process Documentation

Reuse Documentation (Chapter 17) Motivation Reuse Manual

Literate Programming (Chapter 18) Concepts Tool Support Acceptance Reuse Considerations

July 11th, 2005 3

Software Documentation

July 11th, 2005 4

Motivation

Software systems contain all relevant information in order to be executable on a machine.

Human readers need additional information which has to be provided in the documentation of a software system

Software Documentation :: Chapter 16

July 11th, 2005 5

Documentation Categories

Different reader groups have different information needs

End Users need user documentation Managers need process documentation Developers need system documentation Software Component need software

documentation + additional documentation for developers who reuse the component

Software Documentation :: Chapter 16

July 11th, 2005 6

User Documentation Users need different kinds of information and there are

different kinds of users, e.g. novice and experienced users A component may or may not be (directly) used by end users,

thus user documentation of components is optional 5 parts of user documentation

Functional Description – outline of system requirements Installation manual – information on how install the system Introductory manual – informal introduction (for novice users) Reference manual – complete reference (for experienced users) System administrator manual – general information

Software Documentation :: Chapter 16

July 11th, 2005 7

System Documentation It has to capture all information about the

development of a software component/system. System documentation includes:

Requirements – contract between component user Overall design and structure - subcomponents Implementation details – e.g. algorithmic details Test plans and reports – for integration tests Used files – for external files if needed Source code listings – complete description of a

component

Software Documentation :: Chapter 16

July 11th, 2005 8

Process Documentation Describes the dynamic process of its creation for

effective management and project control Documents in process documentation:

Project plan – individual phases with estimates/schedules Organization plan – allocation of personnel Resource plan – allocation of resources Project standards – e.g. design methodology Working papers – technical communication documents Log book – discussions between project members Reading aids – e.g. index of documents

Software Documentation :: Chapter 16

July 11th, 2005 9

Reuse Documentation

July 11th, 2005 10

Motivation

Reuse documentation provides: The evaluation of components in a set of possible

candidates The understanding of a component's functionality The use of a component in a certain environment The adaptation of a component for specific needs

Good documentation of component is essential to software reusability

Documentation must be valued as an essential part of a software component.

Reuse Documentation :: Chapter 17

July 11th, 2005 11

Motivation {2}

Each component has its self-contained documentation

Documentation has to respond some questions like: What kink of component is it? What is the component's functionality? Can the component be reused in our context? How? What else is needed to reuse the component? Can the component be customized/adapted/modified? How? Can the component be interconnected with other

components? Is the component's quality sufficient for our purposes?

Reuse Documentation :: Chapter 17

July 11th, 2005 12

Reuse Manual

It must contain all relevant reuse information according to the type of a component;

Kinds of information: General information – general information for evaluation

purposes (overview); Reuse information – detailed information for actual reuse Administrative information – info about legal constraints

and available support Evaluation information - Detailed information for

evaluation purposes Other information – additional information, e.g.

references

Reuse Documentation :: Chapter 17

July 11th, 2005 13

General Information It should provide enough information to decide whether a

component is a candidate in a certain reuse scenario but not too detailed;

Some parts needed: Introduction - it should contain a clear statement about the

component's function; Classification – related area; Functionality – it gives an overview of all externally visible

operation and provides interface descriptions; Platforms – which platforms the component can be used; Reuse status – What is the status of the quality of the component

with regard to test, maintenance, finances;

Reuse Documentation :: Chapter 17

July 11th, 2005 14

Reuse Information

It contains the essential information for actual reuse. Details necessary:

Installation – which steps (if any) have to be done for incorporation the component into a system

Interface descriptions – definitions for the entire functionality

Integration and usage – How can the component be reused correctly?

Adaptation – How and to what specific needs the component be adapted ?

Reuse Documentation :: Chapter 17

July 11th, 2005 15

Administrative Information

It contains the administrative information such as legal constraints and available support. Procurement and support – e.g. Contact, help, ownership

information Commercial and legal information – e.g. Purchase and

commercial license or permission required? History and versions – history and current version of the

component, a status report

Reuse Documentation :: Chapter 17

July 11th, 2005 16

Evaluation Information It contains more detailed information for the evaluation of a

component, including known bugs, limitations and quality statements. Specifications

Contain components functionality in full detail Quality

Test results, available test data, verification data Performance and resource requirements

E.g., memory, processor, runtime Alternative components

Similar components the could be used instead this one Known bugs

Unresolved problems and desired enhancements

Reuse Documentation :: Chapter 17

July 11th, 2005 17

Evaluation Information {2}

Test support Test cases and/or test environment for the component

Interdependencies Can the component be used stand-alone or must other

components be used with it? Component composition (Chapter 7)

Reuse Documentation :: Chapter 17

July 11th, 2005 18

Other Information

Any other information not covered by the first four parts System documentation

Implementation information such as requirements, design, tests

References Are there references to any literature or other documentation

which are useful for the reuse of the component? Reading aids

Additional reading aids like index, table of components, list of figures, and list of tables help in navigating through extensive documents

Reuse Documentation :: Chapter 17

July 11th, 2005 19

Literate Programming

July 11th, 2005 20

Motivation

The central idea is to improve documentation quality by describing problems and solutions rather than write executable programs.

Literate programming is primarily for system documentation.

Literate Programming :: Chapter 18

July 11th, 2005 21

Concepts

Literate programming is to make programs as readable as ordinary literature.

The idea is construct software systems with better documentation. Points of literate documentation:

Integration of source code and documentation; Problem descriptions; Logical subdivisions – e.g. Chapters and sections; Logical order; Reading aids – e.g., cross references and indexes;

Literate Programming :: Chapter 18

July 11th, 2005 22

Tool Support

Most literate programming tools automatically provide extensive reading aids like tables of contents and indexes.

These tools are used for entire documentation of software components.

The advantage is that the component are documented in a consistent way.

E.g. description about the fluxes of the program, into the source code

Literate Programming :: Chapter 18

July 11th, 2005 23

Acceptance

Lack of tool support and tool integration

The more complex software systems get, the more support tool is needed

Literate Programming :: Chapter 18

July 11th, 2005 24

Reuse Consideration

It provides help in keeping documentation complete and consistent.

Literate programming is clearly aimed at system documentation.

For white-box reuse, system documentation becomes important for the reuse process.

It is important for reuse because it supports both creating high-quality documentation and keeping it consistent and complete.

Literate Programming :: Chapter 18

July 11th, 2005 25

References

SAMETINGER, J. Software Engineering with Reusable Components. Springer-Verlag, 1997.

“porque a vida não é só fantasia”