University of Kansas ITTC Software Projects Life Cycle - Phases of a project Research version of cycle Deliverable Product version of cycle Best Practices

University of Kansas

ITTC Software Projects

• Life Cycle - Phases of a project• Research version of cycle

• Deliverable Product version of cycle

• Best Practices - Guidelines for executing project phases


ITTC Project Life Cycle/Research

Funding

Best Practices

Specifications Design

Unit Implement

Proposal

Requirements

Unit Testing

Integration

System Testing Demonstration Report

Third Party SW


ITTC Project Life Cycle/ Delivery

Funding

Best Practices

Specifications Design

Unit Implement

Proposal

Requirements

Unit Testing

Integration

System Testing

User Docs

Packaging

Delivery

Maintenance

End of Life

Acceptance


Life Cycle - Proposal

• How is a project initiated?• Response to a Request For Proposal (RFP)

– Request from Govt. for research in a specified field of interest

– Solicitation of Private Sector Companies to sponsor a project.

• Follow on work from earlier project


Life Cycle - Funding

• Receive money from sponsoring entity.• Government - DARPA, NSF, etc.

• Private Sector - Sprint, etc.


Life Cycle - Best Practices

• Best Practices are guidelines for executing the remainder of the project phases

• Best Practices are determined by Principle Investigator (PI) and staff for each project.

• Best Practices are derived from ITTC Best Practices template.

• Delivery of Best Practices are via WWW pages.


ITTC Best Practices

• Key driver for Best Practices usage is knowledge capture.• Knowledge capture occurs with documentation.

• Knowledge capture is critical with a high personel turnover rate

– Project life times can range from 1 to 4 or more years.

– Student duration at ITTC averages 1.5 years.

• SW reuse is facilitated through documentation

– Software is frequently shared between projects.

• Best Practices can answer many common new hire SW development questions.


ITTC Best Practices (cont)

• Best Practices provide a mechanism for structured/organized software development• Defined directory structure

– Developers know where to put files

• Source code Version Control System– Revision histories are automatic– Specific versions of the project are easily captured/retrieved

• Source code templates– Source code structure is consistent through the project

• Naming conventions– File/Directory– Document Names– Source code Identifier Names


Document Relationships

• Requirements - describes environment outside the software (SW).

• Specifications - Describe the interface between the environment and the software.

• Design - describes the internal design of the software.


Document Relationships (cont)

Environment

Software

Requirements

Specifications

Design

Interface

Actors

Information


General Document Best Practices

• Use Microsoft Word to generate document.• Use Microsoft Powerpoint to generate pictures

and presentation slides.• Use present tense sentences.• Omit the words ‘I’, ‘we’, and ‘you’ in

sentences.• Use ‘shall’ for items that must be executed.• Use ‘should’ for items that are goals.


Life Cycle - Requirements Docs

• Requirements describe the environment the SW exists in and WHAT the SW must do.

• Requirements are typically the first documents created for a project.• The environment is known.

• The software behavior is known.

– In a research setting requirements for two or more sets of behaviors may be written

– There are two or more project threads.

• The specifics of the interfaces are unknown.

• The design is unknown.


Requirements Docs (cont)• Requirements capture the intent of a project for

future team members.• Requirements consist of the following:

• Environment actor characteristics

– People

– Computers and hardware

– External Software

• Description of data passed between the actors and the SW and under what circumstances

• What the SW must do with the data or what the data does to the software

• Restrictions and necessary performance of Actors, Data and SW


Requirements Docs (cont)

• On most projects a hierarchy of requirements are created.

• There are two routes to creating the requirements hierarchy• Make sub requirements documents that expand on general

higher level requirements. This can be recursive.

• Make a requirements document, specifications document and design document. From the design document logical divisions of project can be made. Requirements are written for each project division. This can be recursive.


Requirements Docs Best Practices

• Each Requirement doc must have the following:• Title page

– Project name– Document version– Author’s name

• ITTC Copyright Page• Introduction Section

– Describe what the document contains.• Requirements Section

– Describe Environment Actors– Describe data passed between Environment and SW– List of what SW is required to do to interact with

environment.


Requirements Docs Best Practices– Each requirement must have a unique ID within the

document.– Requirement Ids must not be changed or reused.

– Requirement Ids are referenced in other requirement, specification and design documents and possible in source code.

– If the requirement expands on a higher level requirement the higher level requirement must be references by Requirement Document name and Requirement ID.

• Deprecated Requirements Section– Requirements that are no longer used are moved to this

section for historical purposes.• Revision History

– List who changed the document, when and why and what the version number was.


Life Cycle - Specification

• Interface Specification is the description of IO interfaces between the environment and SW.

• Specification Documents typically are created following the creation of Requirements Documents.• Requirements documents list the interfaces that are required

• Specification documents describe the details of the interfaces.

• Typically there is a Specification document written for each Requirement Document at the lowest level in the requirements hierarchy.


Specification Docs

• Specifications are a mechanism for unambiguous communication of interface information between project team members.

• Specifications preserve interface knowledge for future team members.


Specifications Doc Best Practices

• Specifications Documents must contain the following:• Title page - Same as Requirements

• ITTC Copyright Page - Same as Requirements doc

• Introduction Section - Same as Requirements doc

• Specifications Section

– User Interface– Application command line arguments

– Graphical windows and menus

– Other hardware interface devices (finger print scanners)

– File formats

– Communication protocols


Specification Docs Best Practices– Application Program Interface (API)s

– Function Interfaces

– Object classes

– Data structures

– Each specification must have a unique ID within the document.

– Specification Ids must not be changed or reused.

– Specification Ids are referenced in other specification and design documents and in source code.

– Requirement(s) that the specification satisfies must be referenced using the Requirement Document name and Requirement ID.

• Deprecated Specifications Section - Same as Requirements doc

• Revision History Section - Same as Requirements doc


Life Cycle - Design

• Design is HOW the SW meets the Requirements and uses the Specifications

• Design documents are written after the Requirements and Specifications are written and before implementation.

• The design process detects problems with Requirements and Specifications before implementation.

• Well designed software greatly reduces time required for implementation.


Design Docs (cont)

• The Design document captures the information needed by future team members to debug or modify the software.

• Design documents with typically be developed in a hierarchy.• A System Level Design document is typically the first design

document created.

– The system level design document divides the project into well defined sub projects. example: user interface, database

• Design Documents are created for each sub project.

– The design is iteratively subdivided until a level is reached where implementation is straight forward.


Design Docs Best Practices

• A Design Documents consists of the following:• Title page - Same as Requirements

• ITTC Copyright Page - Same as Requirements doc

• Introduction Section - Same as Requirements doc

• Design Section

– The design provides enough flexibility that during implementation the design does not have to be rewritten when small changes are made in the implementation.

– Programming Language is determined

– Functional divisions of software and their relationships are described.


Design Docs Best Practices (cont)– Design description mechanism to use include:

– Control Flow Diagram

• Thread relationships

– Data Flow Diagram

– State Transition Diagrams

– Object/Class Relationship Diagram

– Internal APIs

– Unit test design for functional level designs– Unit level testability must be designed into the software.

• Revision History

• Each design must pass a design review before implementation begins.


Life Cycle - Implementation

• Implementation consists of coding the design• Creating directory structures

• Setting up a build mechanism

• Coding

– Language sensitive editors

– Internal Documentation

– Coding for testing

• Using a Version Control System


Implementation Best Practices

• All source files must contain the following:• ITTC Copyright - ALL RIGHTS RESERVED

• Header

– Synopsis -one sentence about the file contents

– Usage ( form ‘main’ files, Makefile’s and scripts)

– Author and Date info

• Internal documentation

– Source files must be understandable by future project members

– Correct, Clear, Complete– Wrong documentation is worse than no documentation

– Programmers unfamiliar with the code will have to work on it


Implementation Best Practices– Interface Descriptions

– Algorithm Description (not pseudo code)

– Use language constructs for code clarity– Identifiers should be full nouns/verbs or STANDARD

abbreviations

– Use spaces around operators (= , ! < )

– Indent execution control statements (if, for, switch)

• One API function or class per source file

– Use multiple local functions in a file.

• Short functions - less than 100 lines

• Make a new function when tempted to copy and paste code.


Implementation Best Practices

• Unit testing mechanisms must be incorporated• Debugging output

• Test scripts/programs

• Source Templates are used to assist in following the Best Practices

• All code must pass a code review.• Development must occur on a VCS branch.• Code may only be merged to the ‘trunk’ when it

passes unit tests.


Life Cycle - Unit Testing

• Unit testing consists of executing code from a project unit and comparing the output to a GOLD output.• GOLD output is correct output for the unit.

• Unit testing detects unexpected ‘bugs’ when an implementation changes.• A coder may not anticipate the total impact of an

implementation change.

• Unit testing may detect untested implementation changes before use by others on a project.


Unit Testing Best Practice

• The unit implementor is responsible for creation of the GOLD output.

• Automated Unit Tests are performed at a regular interval (daily, weekly)• Complete compilation

• Unit output comparison with GOLD output.

• Automated Unit Tests are performed on a Version Control System ‘trunk’

• Compilation errors and test failures are reported.


Life Cycle - Integration

• Integration pulls together the individual project units into a full system.

• With good Specifications and Design this process is smooth.• Poor Specifications and Design should be detected early in the

project but will definitely be detected here.


Life Cycle - System Testing

• System testing is similar to Unit testing but encompasses the whole project.


Life Cycle - Demonstration

• Near the end of most research projects a demonstration is performed for the project sponsor.

• Demonstrations also occur during the life of a project.


Life Cycle - Report

• Research projects require a final project report to be written at the end of the project.• The PI is typically responsible for the final report with input

from the students and staff.

• Excerpts from student documentation, presentations and research papers created during the project are used in the report.

• Research projects also have progress reports at regular intervals.