Contents

  1. Planning
    1. Requirements specification
      1. Purpose
      2. Instructions
        1. Functionality
        2. Performance
        3. Design constraints
        4. Attributes
        5. External interfaces
      3. Document structure
      4. Requirements check-list
        1. Content
        2. Completeness
        3. Quality
    2. Project plan
      1. Do's and Don'ts
      2. WWWWWHH planning
      3. Document structure
    3. Technical specification
      1. Document structure
    4. Testing plan
      1. Document structure
  2. Implementation
      1. Coding rules
        1. Some random texts and resources
        2. Books
  3. Testing
    1. Unit testing
    2. Integration testing
    3. Formal Qualification testing
  4. Project management
    1. Planning
    2. Inspections
      1. Inspection meeting
      2. Inspection meeting memo template
    3. Reporting
    4. Document reviews
    5. Final report

Planning

Requirements specification

Purpose

The Requirements (Analysis) Specification is a reference point for possible functional system changes during the software life cycle. It is also the basis for the test planing and for the acceptance test.

IEEE 830 - 1993 Standard gives detailed instructions how to do a requirements analysis and the specification.

The Requirements specification must answer the "What"-question: What must your software do?

Also, the use case driven approaches can be used. One solution is to follow the IEEE standard, and append the use cases into an appendix.

Instructions

The requirements definition is normally a group work between SW developer, possible project purchaser, marketing staff and the end user. Questionnaires, user surveys, checklists and/or prototyping may be used.

The specification is inspected before proceeding to subsequent phases. Clear acceptance criteria for the SW should be derived from the specification.

ISO 9000-3 recommends that attention should be given to the following issues:

Pressman R.S. [PRE1997] suggests a set of operational principles for requirements analysis:

Davis [DAV1995] suggests a set of guiding principles for "requirements engineering":

Annotate each requirement. Minimum annotation classifies a requirement as essential, desired, or optional. [PHI2000]

Regardless of form, each requirement should include elements of five content areas: [PHI2000]

Functionality

Performance

Design constraints

Attributes

External interfaces

Document structure

1. Introduction 
1.1. Purpose 
1.2. Scope 
1.3. Acronyms and definitions 
1.4. References 
1.5. Overview 
2. General description 
2.1. Product perspective 
2.2. Product functions 
2.3. User characteristics 
2.4. General constraints 
2.5. Assumtions and dependencies 
3. Structural overview and specific requirements 
3.1. Functional requirements 
3.2. External interface requirements 
3.3. Performance requirements 
3.4. Design constrains 
4. General requirements 
4.1. Security requirements 
4.2. Reliability requirements 
4.3. Maintainability requirements 
4.4. Portability requirements 
4.5. Installation requirements 
4.6. Administration requirements 
4.7. Diagnostics requirements 
5. Software generation and integration

A ReqSpec.doc for the inspection meeting memo is available.

Requirements check-list

From "Code Complete", by Steve McConnell (1993) pp. 33-34:

Content

Completeness

Quality

Project plan

The first important step in project planning is to choose a development process that will fit the product and people.

The second major step in planning is to derive tasks and a way to execute them according to the process model chosen.

Standards play a significant role in planning. The IEEE's standard [1058.1 - 1987] states what should be in a project plan and how to arrange the contents. How to make a good plan [Dwayne Phillips]

Planning attempts to predict a software product. You cannot produce a large, complex software product successfully without it. It tells everyone what you want to happen, not so much what you expect to happen.

Planning is concerned with business goals. Solutions must serve the business in a timely and economic manner. They must accurately represent what software people can do for the business.

A plan requires four basic items:

Do's and Don'ts

WWWWWHH planning

WWWWWHH : Why, What, When, Who, Where, How, How Much (part of spiral software design)

Document structure

Format of a software project management plan written according to the IEEE Std-1058.1-1987. 

1. INTRODUCTION 
1.1. Project Overview
1.2. Project Deliverables 
1.3. Evolution of the SPMP
1.4. Reference Materials
1.5. Definitions and Acronyms
1.6. Overview of the Document

2. PROJECT ORGANIZATION 
2.1. Process Model 
2.2. Organizational Structure 
2.3. Organizational Boundaries and Interfaces
2.4. Project Responsibilities 

3. MANAGERIAL PROCESS
3.1. Management objectives and Priorities
3.2. Assumptions, Dependencies, and Constraints
3.3. Risk Management
3.4. Monitoring and Controlling Mechanisms
3.5. Staffing Plan

4. TECHNICAL PROCESS 
4.1. Methods, Tools and Techniques 
4.2. Software Documentation 
4.3. Project Support Persons and Functions 

5. WORK PACKAGES, SCHEDULE, AND BUDGET
5.1. Work packages
5.2. Dependencies
5.3. Resource Requirements
5.4. Budget and Resource Allocation
5.5. Schedule

A PrjPlan.doc for the inspection meeting memo is available.

The introduction is an overview of the people, process, and product for the project. It also states how to change the plan and defines key concepts.

Project organization describes how the people and process will be organized to produce a product. It shows the process model for the project (waterfall, evolutionary, spiral). It also discusses who's who in the project, their areas of responsibility, and their lines of communication.

Managerial process describes how the project manager will ensure that the project adheres to the plan. It contains constraints, policies, objectives, assumptions, and so on. It discusses risk management and the staffing plan (Rayleigh model). It also discusses how the project manager and upper management will obtain project status from the audits and status accounting the Configuration Management staff performs.

Technical process addresses the details of the software process, pointing to several other documents, such as commercially available texts and standards. The section specifies the type of computers, compilers, and component libraries, and so on. It also lists the other documents to be produced, including standards on how to write such documents, and their contents. It concludes by describing the support organizations and their functions in the project. These may include the Configuration Management staff, an independent verification and validation group, security staff, facilities maintainers, and technical writers.

The final section is "the plan". The task (work package) network is the foundation of this section. This is the place to sum up the time, cost, and equipment scattered throughout the network.

Technical specification

The technical design specification, or Software Design Description (SDD) describes the internal design of the software system. This formal specification will present a design to meet the requirements that the system is to achieve. It brings together the assumptions of the environment and the requirements presented in the software requirements specification, into a description of the software structure, software components, interfaces, and data necessary for the implementation phase. In essence, the SDD becomes a detailed blueprint for the implementation activity. In a complete SDD, each requirement must be traceable to one or more design entities.

The Technical specification must answer the "How"-question: How will your software fulfill the requirements?

In documenting the design of a software artifact, several different views of the design need to be considered, so as to meet the requirements of the different users of the design. Possible design views to be considered for incorporation in a Design Document include:

A selection of approaches is available for the design documentation. Those the project group are most familiar with might be the safest solutions. Course literature exists for familiarizing with the others.

IEEE Std 1016.1, Guide to Software Design Descriptions, provides examples of what should be included in a Design Document for a number of different design approaches.

For example, using the SA/SD, the Decomposition Description would be defined by Structure Charts; the Dependency Description would be defined by a set of Data Flow Diagrams; the Interface Description would be defined in a Data Dictionary and Context Diagram; and the Detail Description would be defined in the Process Specifications.

The selected design methodology should be identified. Some of the possibilities are listed below. Any combination seen best can be chosen.

Document structure

The following sample Table of Contents for a Software Design Description is based on ANSI/IEEE Std 1016-1987, Recommended Practice for Software Design Descriptions. 

1.  Introduction
  1.1  Purpose
  1.2  Scope
  1.3  Definitions and Acronyms
2.  References
3.  Decomposition Description
  3.1  Module Decomposition
    3.1.1  Module 1 Description
    3.1.2  Module 2 Description
  3.2  Concurrent Process Description
    3.2.1  Process 1 Description
    3.2.2  Process 2 Description
  3.3  Data Decomposition
    3.3.1  Data Entity 1 Description
    3.3.2  Data Entity 2 Description
4.  Dependency Description
  4.1  Intermodule Dependencies
  4.2  Interprocess Dependencies
  4.3  Data Dependencies
5.  Interface Decomposition
  5.1  Module Interface
    5.1.1  Module 1 Description
    5.1.2  Module 2 Description
  5.2  Process Interface
    5.2.1  Process 1 Description
    5.2.1  Process 1 Description
6.  Detailed Design
  6.1  Module Detailed Design
    6.1.1  Module 1 Detail
    6.1.2  Module 2 Detail
  6.2  Data Detailed Design
    6.2.1  Data Entity 1 Detail
    6.2.2  Data Entity 2 Detail

A TecSpec.doc for the inspection meeting memo is available.

Testing plan

The purpose of a Test Plan is to describe the testing processes, defining the test domain, test strategy, test philosophy, test exit and entrance criteria, test configurations, and test tools employed to verify and validate a set of functionality. The Plan should also include information on schedules, resource allocations, and staff utilization.

The following IEEE standards provide more information on formal testing documentation:

Document structure

For this course, one of the following structures is proposed into use. Other structures are accepted, but the used practice should preferably follow some accepted standard, and a reference should be given.

One example of a detailed structure: 

1. Introduction
  1.1 Overall Description
  1.2 Test Plan Purpose
  1.3 Test Plan Approach
2. Test Items
3. Tested Features
4. Features Not Tested
5. Testing Strategy and Approach
  5.1 Syntax
  5.2 Description of Functionality
  5.3 Arguments for tests
  5.4 Expected Output
  5.5 Specific Exclusions
  5.6 Dependencies
  5.7 Test Case Success/Failure Criteria
6. Pass/Fail Criteria for the Complete Test Cycle
7. Entrance Criteria/Exit Criteria
8. Test Suspension Criteria and Resumption Requirements
9. Test Deliverables/Status Communications Vehicles
10. Testing Tasks
11. Hardware and Software Requirements
12. Problem Determination and Correction Responsibilities
13. Staffing and Training Needs/Assignments
14. Test Schedules
15. Risks and Contingencies
16. Approvals

An example of an informal structure: 

1. Introduction 
2. Unit Test Description 
3. Integration Test Description 
4. Validation Test Description 
5. Testing Process Sequence 
  5.1 Unit Test Cases 
  5.2 Integration Test Cases 
  5.3 System Test Cases

Implementation

Coding rules

Spend even more time on the design before writing any lines of code. The more planning, the better the program.

Working on large software projects teaches quickly what one should never do, and this learning from mistakes can be avoided by studying documentation and books describing the problems of others. From them, you will quickly learn why design documents, coding standards and code comments improve the overall quality of the software.

Beauty is in the eye of the beholder. When writing code you should aim at readability with useful comments added, resulting in maintainable code. Efficient and documented algorithms should be researched, and if already researched, they should be re-used, not re-invented. There exists several different naming conventions, but the main point is that the same naming convention, whatever it is, is used everywhere in the project, and hopefully is inherited from earlier project files which are re-used. Some people say the code is not supposed to be pretty, but operational. This is fine if there is only one person working on the project and nobody will ever re-use any parts of it. Otherwise, always remember readability and documentation. If the code has to look ugly (perhaps due to optimization?), then explain the reasons behind it to the reader. Links

Here you should find links to coding guidelines, and other resources in the internet. Please let me know if you know of any links that I should add.

Some random texts and resources

Some coding guidelines:

Some documentation guidelines:

Source code documentation generator tool

Books

Some books worth reading:

Testing

Unit testing

Integration testing

Formal Qualification testing

Project management

Planning

Inspections

Inspection session are proved to be the most efficient way to assure software quality. It is very simple and cost efficient way to eliminate mistakes in different phases of the project. The reason is simple; nobody wants to give a document to be inspected if it is not properly prepared. So designer will do their work more carefully when they know that there will be a meeting for inspecting the document.

However, it needs some preparation and training. Inspection session must be held very professional manner. The inspection and critic is for the product not for the author of the for example design document. So keep in fact and details.

Is is as well important that the author will deliver the documents to be inspected few days advance. This way participants can prepare and must prepare carefully for the inspection.

Inspection meeting

Inspection meeting is a formal meeting, which takes time from one hour to four hours. Longer meetings are not efficient, because people are later too tired to concentrate on important issues.

There are different roles for the participants in inspection meeting:

First issues are always formal:

Then the facts:

Inspection meeting memo template

A Template for the inspection meeting memo is available.

Reporting

Document reviews

Final report

some topics for the final report:

DuringTheProject (last edited 2009-01-09 14:56:33 by chwieser)