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, 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 11 th, Software Documentation

July 11th, 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, 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, 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, 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, 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 11 th, Reuse Documentation

July 11th, 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, 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, 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, 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, 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, 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, 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, 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, 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 11 th, Literate Programming

July 11th, 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, 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, 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, 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, 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, References SAMETINGER, J. Software Engineering with Reusable Components. Springer-Verlag, “porque a vida não é só fantasia”