CPSC 451 Practical Software Engineering

Course CPSC 451 -- Winter 1996

Instructor: Mildred L.G. Shaw, MS 680H, email: mildred@cpsc.ucalgary.ca;

Class hours: Tues/Thurs 5:00-6:00 pm

Labs: Tues/Thurs 6:30-7:45 pm.

Office hours: Tues/Thurs 12:30-1:30 pm and by appointment.

TA's:

Office hours: TBA and by appointment.

Purpose of Course

To provide an overview of techniques and methodologies for applied software engineering.

Objectives

After completing this course the student will be able to:

Course notes and course books:

Course notes will be on the World-Wide Web at http://www.cpsc.ucalgary.ca/~mildred/451

You are advised to use Netscape to view these documents.

There will be no compulsory text book, but the following are highly recommended:

Reserved Books

Course structure

In order to cover the basic issues and techniques, and to understand future directions there will be two main parts to the course:

1. Techniques in software engineering: covers some of the techniques currently in use in organizations;

2. Large group project: involves the carrying through of a project from specification through implementation and testing, and also the evaluation of another group's project.

Assessment

This is in three parts. All three parts must be passed to achieve a pass in the course. Part A is theory and consists of items 1 and 2 below, worth a total of 40%. Part B is individual record keeping and assessment and consists of item 3 below, worth a total of 10%. It is an essential learning experience for project management, and each report must be submitted by the due date. Part C is practical and consists of item 4 below, worth a total of 50%.

1. Midterm examination

This will be 1 hour in class time (see schedule). It will cover any material in the first 5 weeks of the course. Answers to all exam questions should be written with a pen (NOT pencil) and given in point form if appropriate, with clear examples, unless otherwise specified.

February 8. (20%)

2. Final examination

This will be 1 hour in class time (see schedule). It will cover material from week 7 to week 10 of the course. Answers to all exam questions should be written with a pen (NOT pencil) and given in point form if appropriate, with clear examples, unless otherwise specified.

March 21. (20%)

3. Logs and group reports

(i) This involves an individual record keeping or log of all your activities on the supplier project. Set it out in the form of a diary with dates, what was done, and time spent on each item. Due in with supplier group reports (ii below). Only the current month is required.

(ii) 3 monthly reports of an assessment of each member of your supplier group. You should have one per person (in alphabetical order of last name), including yourself, outlining who did what during the month, and how you assess their work. Some sort of grading on one or more criteria should be applied. (This is in addition to your personal log.)

Each month you should submit to mildred@cpsc.ucalgary.ca; and your TA your own log for the current month and all the previous monthly reports on each person, one person per report. The subject line should contain your supplier group number and your name. Each report should have at the top the name of the person and your name and supplier group number. Each report should be about a third of a page long. You will be marked on how perceptive and reasonable your comments are.

Do NOT submit reports in the same mail as other messages.

Get to know the people in your group as soon as possible, or you will find this difficult.

Due by 1 pm on 30 January, 5 March, and with final project evaluation.

(iii) One final report of an assessment of each member of your customer group. You should have one per person (in alphabetical order of last name), including yourself, outlining who did what during the project, and how you assess their work. Some sort of grading on one or more criteria should be applied as with the supplier reports. Each page should have your name and customer group number at the top. Each report should have the name of the person and should be half a page long. Your customer group number and your name should appear on the subject line Submit as with supplier reports.

Do NOT submit reports in the same mail as other messages. Due by 1 pm on 28 March.

Note: This is NOT optional. (10%)

Hints on writing logs and supplier group reports

4. Project: (50%).

I. Customer.

You will be assigned to a group of about 12 students. (Assignment to groups may be changed when the final class list is known.) Each group will prepare an informal requirements document for the project (subject to be provided) and be responsible for its evaluation and criticism as it progresses. In effect, you will be the customer for the system. You will be expected to be present at all presentations, and comment on the write-ups. Your grade will depend on how thoroughly the evaluation is carried out, the extent to which it is fair and reasonable and the extent with which it agrees with the judgments of your TA. and instructor. Groups are advised to show all first drafts to the TA., and discuss any problems or disagreements. Marks will be deducted for documents that exceed the maximum number of pages specified, and for those which are late. Documents should have a title page which has the title of your project; the name of your group, a list of members and the date. You should submit all documents by putting them up on your web page before 1pm on the required date. Dates as below.

(i) Informal specification of requirements:

This should outline the project and customer requirements. Make sure the project is suitable for completion in one term. Remember that it is not a competition; do not aim to destroy the supplier but give an honest set of requirements. (Marks will be deducted for a project considered too easy or too difficult.) Up to 5 pages, including the title page. 16 January. (2%).

(ii) Functional specification and management plan:

This is to be assessed and evaluated against actual requirements. Make sure that you are satisfied at this stage that your supplier is aiming to meet your requirements. Mark clearly, in italic or bold type on the supplier's document, any comments or amendments on the document. You may add up to 2 additional pages. Do not add any new requirements at this stage, or make the project any larger. 30 January. (6%).

(iii) Overall design document:

The functional specification and the overall design together describe the proposal from your supplier. When accepted, these documents are a contract between you and your supplier about what they intend to deliver. Changes can be negotiated later and should be recorded as an appendix. Mark clearly, in italic or bold type, any comments or amendments on the supplier's overall design document. You may add up to 2 additional pages. 15 February. (6%).

(iv) Presentation:

A preliminary review of about 5 minutes will be presented by the supplier in class, with up to 5 minutes of questions and discussion from you, the customer. Everyone should attend and take part. You should address any points which need clarification or for which you suggest changes, which should be minimal. After you have seen the amendments you will be required to sign a contract with your supplier. Week 6. (4%).

(v) User manual:

As before mark clearly, in italic or bold type, any comments or amendments on the supplier's user manual. 19 March. (4%).

(vi) Demo:

Use the demo time to assess the system and the (possibly revised) user manual. Everyone should attend and take part. You should ensure that the demo relates closely to what has been negotiated and agreed in the contract. In Weeks 11 to 13. (4%).

(vii) Evaluation:

Write a project evaluation (4-5 pages) which should include a discussion of how well the project satisfies your original requirements or what has been added or subtracted; how useful the design process was and what differences (if any) you propose for the design assignment.

Submit by 1pm one day after the demo. (4%).

II. Supplier.

Your group will work with a different group to receive informal requirements for a system, and will produce a more formal specification, produce the analysis and design, code a prototype, evaluate and refine the prototype, and present a final product according to the details below. You will be the supplier of the system. Oral presentations and discussions will be required at various points within the project, and will be evaluated and assessed by the customer. You should submit all documents on the web, before 1 pm on the required date. All documents should have a title page which has on it the title of your project; the name of your group, a list of members indicating who was responsible for which parts, and the date. You should notify (by email) all interested parties concerning any re-submitted documents as soon as they are completed. Groups are required to show all final drafts to the TA. Groups are advised to show earlier drafts to the TA., and discuss any problems or disagreements. Marks will normally be deducted for documents that are late. Dates as below.

(i) Functional specification and management plan (about 15-20 pages):

This should explain what you are going to do for your project as opposed to how you will accomplish it. When writing this, do not assume that your customer has any deep knowledge of computer science. Cost estimation is not required. The functional specification should include a title page which has on it the title of your project; the name of your group (which you can invent); the people who contributed to the document, including authors of individual sections and editor of the whole paper, outside consultants etc; and the date. In about 2 pages you should summarize the project you are working on. Give your system a name and describe what it does and who will use it. What needs will it satisfy? How will it help the users? Outline the most important features of your system. Describe the hardware your system will use, and any important performance goals that it should satisfy, e.g. time or space efficiency, security, or reliability.

The next section of about 10 pages concerns the user interaction and will form the basis of your user manual (see part iv below). It should describe the function that the system will perform from the point of view of the user. Cover the kinds of inputs your system expects, the actions it will take on both expected and unexpected inputs, and the types of outputs the user will see in those cases. (Marks will be deducted for a poor user interface regardless of the opinion of the customers.) Include several sample transcripts of the interaction with your system in the form of a dialogue. Include a glossary of all specialized terms used in the document, either computer science terms that the programmer may not know, or terms from the field in which you are working.

The management plan of about 5 pages should include a breakdown of the different features of the project, the major classes of functions and the relationship between them. It should also include a preliminary decision on your main data structures and algorithms, and a page or so discussing possible implementations. Make sure that you do not give the impression that you are promising more than you intend to deliver. Cover yourself by including a page on a minimal system that you think you can complete by the end of February; and the enhancements you could include if all goes well. Finish with a summary restating the main points you want the customer to remember, then include a page on the structure of your team and who will be responsible for which parts of the project. 25 January. (10%).

(ii) Design documents:

The functional specification and the overall design together describe the proposal to your customer. When accepted, these documents are a contract between you and your customer about what you intend to deliver. Changes can be negotiated later and should be recorded as an appendix. During the design process you should focus on the parts of the design essential to producing a core system, and merely outline extensions to a more complex system -- one of your major goals is to get something working by the deadline!

The main goal of the design process is a detailed design document that is complete enough to be a reference from which any competent computer scientist can produce code and a user manual, and carry out tests. This document will eventually evolve into the code and usually the system maintainer's guide. An intermediate goal is the overall design specification which is a draft of the detailed design document with some of the details missing. Interfaces between modules should be clearly defined. Once the design has been written down, everyone in the group should read the entire document to make sure they understand the design. Individuals should be assigned responsibility for particular modules and should design these in more detail. Each person should review carefully at least one other person's section and all sections should be reviewed by someone other than the author. Pick the one(s) with which your module has the strongest interaction(s).

(iia) Overall design document:

Based on the examination of the module interactions, you should prepare a set of interface definitions. For the overall design document, (about 40-50 pages) you should define your major data abstractions and modules, focusing on the design, submodules, error-handling, exports and imports of the major modules. Fill in as many details as possible in order to get feedback on it. Include sections discussing the modification and the management questions, an executive summary and a list of contents. Make sure that you provide a top-down description of your system. You are advised to consult your TA. frequently on this document. Provisional feedback will be given as an indication of what you might expect for the detailed design document. 9 February.

(iib) Presentation:

A preliminary review of about 5 minutes will be presented in class, with up to 5 minutes of questions and discussion from the customer in Week 6. (Marks will be deducted if this is not well organized or runs over time.) Provisional feedback will be given as an indication of what you might expect for the detailed design document. Week 6. (10%)

(iic) Detailed design document:

The final step is then to prepare the detailed design document. The detailed design document (about 80-100 pages, built on top of the overall design document) should include answers to all the questions for as many levels as possible. Write pseudocode or code outline for all modules (this should be in terms of calls to other high-level functions and be easy to read). Include test schedules as part of this document. Update the sections describing coding responsibilities. Most of the work will be done by individuals filling in the details of their modules, but you must review the document as a whole to make sure people are using the same interface definitions and to make sure that everything has been covered and that the parts of the document hang together.

Testing must be carefully planned and documented as to the order in which modules are to be integrated and the order in which the individual modules are to be completed and tested in isolation. Testing and debugging methods must be agreed on, documented, and carried out. Several stages of tests must be scheduled, and several testing procedures should be explored. Scheduling is required for unit tests, integration testing, functional testing, performance evaluation, and an acceptance test (demo). These should include practice in the techniques of walkthroughs, logic testing and input/output testing. The test and evaluation plan should contain a statement of objectives and success criteria, integration plan e.g. the order in which modules are to be combined, testing and evaluation methodologies, and responsibilities and schedules. You must devise a monitoring process to ensure that tests are designed and carried out on schedule, report lack of compliance to other group members, and decide on a procedure for reporting and correcting bugs.

The test plan (about 10-15 pages) should contain an introductory section that summarizes the objectives, a list of tests and dates and people responsible, summary of the monitoring, reporting and correcting procedures, and proposed dates for submission of individual test reports; a discussion section covering a short defense of the integration plan, details of the tests with objective and success criteria, details of monitoring, reporting and testing procedures, and details of individual group member assignment. Each person should be involved in at least one set of tests. You are advised to use walkthroughs regularly, and to consult your TA. frequently on this document. 22 February. (20%)

(iii) User manual (about 20-25 pages):

This should be a self contained description of how to use your system. It should have a clear structure, a table of contents, and an index. Do not discuss any implementation. It should contain an introduction, a section on how to use the system, error recognition and handling, and a section showing a sample interaction complete with screen dumps, and a list of known bugs and deficiencies. 12 March. (10%).

(iv) Demonstration:

This should exhibit the best features of your system. It will be followed by questions from your customer, with suggestions of input to try, and discussion. With your evaluation you must submit the complete code and a transcript of your demo. (Marks will be deducted if the demo is not well organized.) To be given in Weeks 11 to 13. (10%).

(v) Evaluation:

The final document required is a project evaluation (about 10-15 pages) which should include a discussion of how well your project satisfies your original functional specifications or what has been added or subtracted; how useful the design process was and what differences (if any) you propose for the design assignment; how the test plan worked, how the real management structure resembled the planned one; comparison of actual times taken for each part; how you would have done it differently if it were a "real" project (dissenting opinions in the group may submit an additional statement); and in what way you could make the project less work if you were to do it again. Include a section on "lessons learned" from doing this project. (10%).

The final documents should be submitted by 1 pm two days after your demo.

Summary of marks and dates for the project:

I.

(i) 2%, 16 Jan
(ii) 6%, 30 Jan
(iii) 6%, 15 Feb
(iv) 4%, Wk 6
(v) 4%, 19 Mar
(vi) 4%, Wk 11-13
(vii) 4%, Wk 11-13

II.

(i) 10%, 25 Jan
(iia) 9 Feb
(iib) 10%, Wk 6
(iic) 20%, 22 Feb
(iii) 10%, 12 Mar
(iv) 10%, Wk 11-13
(v) 10%, Wk 11-13

Notes

1. No part will be accepted until all previous parts are completed;
2. The group grade may be adjusted for individuals depending on their contribution to the group.

Summary of other marks and dates:

Logs and reports: 30 Jan, 5 Mar, 28 Mar, 1 day after demo

Exams: (i) 20%, 8 Feb; (ii) 20%, 21 Mar

Lecture Notes

The lecture notes and projests are listed separately.

Course Schedule

N.B. The exact date and time of project group presentation will be assigned by ballot.


Department of Computer Science
mildred@cpsc.ucalgary.ca 13-Mar-96