Software Engineering Guidelines

This is a set of guidelines and documents that should be followed when developing your Sahana project.

Most projects start with a Problem Statement. A Problem Statement is a brief statement of what your project will do. The

[[Media:Problem_Statement_sample.doc|Sample Problem Statement]]

provides instructions for completing a problem statement as well as a sample problem statement. You do not need to be this thorough when describing your intended project, but the sample may provide some guidance in the construction of your description.

Milestone 1: Software Requirements Specification
The first deliverable for your project is a completed Software Requirements Specification (SRS). The link below is to a document that contains a template for creating a software requirements document for the Sahana project. The titles of sections should remain the same. The text contained within each section describes what the content of the section should contain. Replace this text with your own describing your project.

[[Media:Software_Requirements_Specification.doc|Software Requirements Specification]]

The document below contains the Software Requirements Specification for the Volunteer Management Module. Note that this document contains the essence of the requirements as were known in June 2006. Changes may have been made to the Volunteer Management Module since that time that may not be reflected in these requirements. There are also a few areas of incompleteness.

[[Media:Volunteer_Manager_Requirements.doc|SRS for Volunteer Management Module]]

The results of the review of the SRS documents revealed some common issues. These included:
 * Be careful to update the Table of Contents so that each section reference references the correct page.
 * Also update with the individual functions for section 3.
 * Section 1.1. Scope is intended to describe what your project will do and what it will not. There was some vagueness in this section. Be sure to clearly indicate the line that circumscribes what your project will do.
 * Make sure that if you include references, that they’re specific. It wasn’t sufficient to simply reference “Sahana documentation”. You need to provide enough information so that the reader can actually find the document if they want.
 * Section 2.1 Product Perspective is intended to describe how your application fits into the wider Sahana project. If you’re customizing an existing module, say so. Similarly if you’re creating a separate module that integrates into the larger system, say so.
 * Be sure to provide unique IDs and names for the functions in section 3.
 * For the specific functions:
 * the input is the event that the user takes to invoke the functionality. What triggers the functionality?
 * the action is the series of steps taken by the system in response to the event. What does the system do?
 * the output is the explicit and observable response that is provided to the user (or external system).

Milestone 2: Software Design Specification
The second deliverable for your project is a completed Software Design Specification (SDS). The link below is to a document that contains a template for creating an SDS for the Sahana project. As with the SRS, the titles of sections should remain the same. The text contained within each section describes what the content of the section should contain. Replace this text with your own describing your prject.

[[Media:SoftwareDesignSpecification.doc|Software Design Specification]]

Currently, no Software Design Specification exists for the Sahana project. Below is an example Software Design Specification for a Similarity project. The Similarity project is one that takes two or more text and/or HTML files and returns a percentage assessment of the similarity between all pairs of files. Note that the SDS below is very similar in format to the one to be used for Sahana, but is not exactly the same. It is also sample student work and is not perfect. Therefore this document should be used as a guideline.

[[Media:SIMA_SDS.doc|Software Design Specification Example for Similarity Project]]

When developing your SDS, there are some common problems to avoid including:
 * Not using clear and understandable labels for components/entities.
 * Including a diagram (high-level or detailed) with no explanation of it. Diagrams don’t explain themselves and you must tell the reader what is happening in the diagram and its significance.
 * Using different/conflicting names for components.
 * Different name in the diagram and in the discussion.
 * Be careful of this throughout the document.
 * Be consistent with SRS as well.
 * Not clearly relating the design back to the SRS. You want to clearly show how the design is fulfilling the user requirements.
 * Lack of detail in describing the components at a detailed level. Remember that the idea here is that the design is complete enough to hand off to someone to code. So it needs to have enough detail in order to do this.

One approach that you might find helpful is to walk through the major functionality of your project on a component by component basis. Do you have all necessary components? Have you described how the components interact? Is each component sufficiently detailed to support development?