1 Introduction to Software Engineering Lecture 42 – Communication Skills

2 Lecture Outline Purpose of software documentation What makes software documentation different? Styles of software documentations Code: General Recommendations

3 Purpose of Software Documentation Provide a software product in an executable form. Describe the software product The requirements the product is intended to satisfy The design of the product The implementation of the product The capabilities and limitations of the product The product from different perspectives

4 Purpose of Software Documentation Show that the product is correct. Make the product easier to Use Maintain reuse

5 Kinds of software documentations Requirements specifications Design specifications Source code Testing results User manuals

6 What makes software documentation different? Software is not visible Software product is represented and distributed as documentation Software involves formal, machine-readable languages Content of software is largely logic Software documentation has many different purposes Software product needs many kinds of documentation

7 Styles of software documentations Tutorial Teaches some aspect of the software Often used for user documentation Hyperlinked set of documents Requirements are connected to the design, the design is connected to the code etc. Layered set of documents Presents software at different layers of abstraction For example, algorithms are presented separately from the code.

8 Styles of software documentations Single-source document Different documents and different views are generated from a single source Example: javadoc Example: a family of manuals generated from the same source.

9 Code: General Recommendations Structure the code in a consistent manner. Express the structure of the software’s design in the software's code. Follow the conventions of the programming language being used.

10 Commenting code Begin every code file with: Authors Description of contents Revision date and log of changes made to the file. Comment: Each variable declaration Each procedure definition Loops and larger blocks of code Avoid excessive comments in procedure bodies Wrtie code so that what it does is obvious

11 Key Points Purpose of software documentation is to describe the software product. Kinds of software documentations Code documentation Authors and revision details Comments variables, procedures, loops etc.