TSIMMIS Project Stanford University
Guidelines for Developers
Suggestions for Efficient Software Design & Implementation
Joachim Hammer and Ramana Yerneni
Stanford University
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
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
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.
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.
Deliverables: drawings, informal documentation, pseudo code
Deliverables: working code, acceptance test criteria for each (i.e., some measure of when you think your code will be ready for installation )
Deliverables: Status of code, bug list, fixes
Deliverables: Final documentation, status of software and possible enhancements
This section is probably not as useful for Tsimmis but we decided to include it nonetheless.
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:
The following list describes some of the concepts that arise in project management. We have included them here for your information.