Software Engineering with Reusable Components

1
Software Engineeringwith Reusable Components

• RiSEs Seminars
• Sametingers book Chapters 16, 17 and 18
• Fred Durão

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

3
Software Documentation
4
Motivation
Software Documentation Chapter 16

• 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

5
Documentation Categories
Software Documentation Chapter 16

• 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

6
User Documentation
Software Documentation Chapter 16

• 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

7
System Documentation
Software Documentation Chapter 16

• 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

8
Process Documentation
Software Documentation Chapter 16

• 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

9
Reuse Documentation
10
Motivation
Reuse Documentation Chapter 17

• 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.

11
Motivation 2
Reuse Documentation Chapter 17

• 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?

12
Reuse Manual
Reuse Documentation Chapter 17

• 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

13
General Information
Reuse Documentation Chapter 17

• 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

14
Reuse Information
Reuse Documentation Chapter 17

• 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 ?

15
Administrative Information
Reuse Documentation Chapter 17

• 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

16
Evaluation Information
Reuse Documentation Chapter 17

• 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

17
Evaluation Information 2
Reuse Documentation Chapter 17

• 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)

18
Other Information
Reuse Documentation Chapter 17

• 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

19
Literate Programming
20
Motivation
Literate Programming Chapter 18

• 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.

21
Concepts
Literate Programming Chapter 18

• 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

22
Tool Support
Literate Programming Chapter 18

• 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

23
Acceptance
Literate Programming Chapter 18

• Lack of tool support and tool integration
• The more complex software systems get, the more
  support tool is needed

24
Reuse Consideration
Literate Programming Chapter 18

• 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.

25
References

• SAMETINGER, J. Software Engineering with Reusable
  Components. Springer-Verlag, 1997.
• porque a vida não é só fantasia