TSIMMIS Project Stanford University

Guidelines for Developers

Suggestions for Efficient Software Design & Implementation

Joachim Hammer and Ramana Yerneni

Stanford University

1. Introduction

2. The Software Design Process

2.1. Requirements Analysis
2.1.1. Survey the current situation (if applicable)
2.1.2. Specify the new project requirements
2.1.3. Specify the interface (external) requirements
2.1.4. Specify test scenarios
2.1.5. Review
2.2. Physical Design
2.2.1. Develop the (internal) design
2.2.2. Design a test suite
2.2.3. Review
2.3. Implementation
2.3.1. Coding
2.3.2. Code review
2.3.3. Unit testing & debugging
2.3.4. Develop comprehensive integration tests
2.4. Test and Integration
2.4.1. Fix testing
2.4.2. Regression testing
2.4.3. Acceptance test
2.5. Installation and Release
2.5.1. Educate potential users
2.5.2. Install and integrate with existing software
2.6. Maintenance
2.6.1. Implement change requests
2.6.2. Collect performance data
2.6.3. Demonstrate software
2.6.4. Train additional users

3. General Observations

4. Project Management Issues

4.1. Resources
4.2. Schedule
4.2.1. Estimation
4.2.2. Contingency planning
4.3. Coding Standards
4.3.1. Version control
4.4. Teamwork
4.5. Documentation

1. Introduction

The following document describes the software engineering process that we are planning to adapt for the TSIMMIS project at Stanford University. We hope that the following set of guidelines will enhance the productivity of the group as a whole and of each individual implementer, and make the management of the project considerably easier in the years to come. Feel free to make suggestions on how this process can be further improved. Send comments to joachim@cs.stanford.edu.

2. The Software Design Process

The software development process is an iterative, team-oriented process beginning with the definition of system needs and ending with a product that is supposed to perform one or more specific tasks. The development process consists of a set of related activities that result in some form of output; usually one of review, document, or code. In order to accommodate the different goals and the less formal development environment of academic projects the software design process that we are adapting for the Tsimmis project is considerably more relaxed and simpler than those used in industry.

The following list of steps is meant to be a guide for each implementer rather than a mandatory list of steps that has to be followed to the last detail. However, we expect that everybody who writes code for Tsimmis understands this software engineering process and follows the steps below whenever appropriate and as closely as necessary.

2.1. Requirements Analysis
2.1.1. Survey the current situation (if applicable)
• what is already installed, how does it work, what needs to be changed?
2.1.2. Specify the new project requirements
• what are the required functionalities and features, how are errors handled?
2.1.3. Specify the interface (external) requirements
• how does the outside interact with the new module(s)?
2.1.4. Specify test scenarios
• how can we test the new module(s)? alone and integrated with other pieces
2.1.5. Review

Deliverables: preliminary design specification describing the functional requirements

During this phase, interactions among the team members can be either via e-mail or through informal meetings. However, it is important that everybody on the team has a chance to participate in the discussions and make inputs. The output can be as informal as an e-mail write-up or as formal as a complete document.

2.2. Physical Design

2.2.1. Develop the (internal) design
• hardware platform: what is the programming environment (determines choice of programming tools later on)?
• language issues: what programming language are we using? compilers, tools, etc.
• data structures: what are the major data structures for holding the input, intermediate data, and output?
• design algorithm

2.2.2. Design a test suite
• put together scenarios to test the various angles of your algorithm

2.2.3. Review

Deliverables: drawings, informal documentation, pseudo code

2.3. Implementation

2.3.1. Coding
2.3.2. Code review
• review of code by team members who did not implement it
• identification of bugs, problems, areas of improvement
2.3.3. Unit testing & debugging
• test each piece separately before starting to integrate
2.3.4. Develop comprehensive integration tests

Deliverables: working code, acceptance test criteria for each (i.e., some measure of when you think your code will be ready for installation…)

2.4. Test and Integration

2.4.1. Fix testing
2.4.2. Regression testing
2.4.3. Acceptance test

Deliverables: Status of code, bug list, fixes

2.5. Installation and Release

2.5.1. Educate potential users
• explain how to use the software
2.5.2. Install and integrate with existing software
• coordinate with other team members how and when to best install your code

Deliverables: Final documentation, status of software and possible enhancements

2.6. Maintenance

This section is probably not as useful for Tsimmis but we decided to include it nonetheless.

2.6.1. Implement change requests
• fix bugs specified in 2.5, implement user changes if feasible
2.6.2. Collect performance data
• observe the performance of software, make recommendations for possible enhancements
2.6.4. Demonstrate software
• usually to our funding agencies or at workshops in order to increase visibility of the project
2.6.4. Train additional users
• in our case this means that we have to show people from the funding agencies how to use the code and how they can show it to others.

3. General Observations

The first thing you should note is that every phase has an input (which is the output of the previous phase) and an output (which becomes the input to the next phase). The input to the first phase is the idea, the proposal, or the contract on which you base the project. Documents can be as informal as an e-mail message sent to all participants or as formal as a type-set user's manual for delivery to the customer. The most important thing to remember is that all participants must be kept informed about what is going on at all times during the development cycle. Thus it is imperative that you share your ideas, plans, decisions, etc. in writing and make them available for discussion. Furthermore, by writing things down, you have the ability to go back and revisit your decisions in case the project requirements change or you find out that you have run into unforeseen difficulties.

Most of the steps listed above are based on common sense, and many of these concepts are well known clichés (i. e., "…always document your code…", "… write good documentation…", "… perform thorough tests…", etc.). The challenges for good software design lie in putting those ideas to practice without adding a extra burden on the project members. One of the most fundamental decisions in software engineering is to find the right mix between scheduling requirements (e.g., how firm are the deadlines?) - scope (e.g., is it a small internal project or a multi-million dollar multi-year contract) - resources (e.g., how many people for how long with what skill sets?). Therefore, the way we design and develop our code will depend on the urgency of delivery, the length and budget of the project, and how many people we have available at any given time: from informal (reviews and specs via e-mail to semi-formal with design and review meetings and written specifications). However, there are several key habits that should always be practiced, no matter how urgent the deadline or how few resources participate in the overall effort:

1. Write down your design specification. This can be either a document or a powerpoint drawing explaining the architecture of your module
2. Document your code
3. Use versioning tool. In Tsimmis we use RCS. For a brief tutorial on how to use RCS, go to the tutorial page.
4. Write documentation explaining how to use your module (both from a user's and an implementer's perspective)

4. Project Management Issues

The following list describes some of the concepts that arise in project management. We have included them here for your information.

4.1. Resources
• people, software and hardware tools, knowledge, training
4.2. Schedule
4.2.1. Estimation
• a rough estimate is: 5 hrs./person/day, 5000 lines/person/year
4.2.2. Contingency planning
• slack planning, scope alteration, resource alteration, schedule alteration
4.3. Coding Standards
4.3.1. Version control
• project level versioning, libraries
4.4. Teamwork
• good communication, reviews and feedback, mutual learning, team spirit
4.5. Documentation
• extent and format depending on the intended purpose