CS-731: Software Practicum

Introduction

CS-731 is one of three courses that Master's students may use to satisfy the "capstone requirement" for the MA degree in Computer Science at Queens College. The other two courses are CS- 732 (Research Practicum) and CS-733 (Master's Thesis).

Prerequisites

Description and Requirements

Each student designs and implements a "significant" programming project for this course. The definition of "significant" is imprecise, but a rough guideline would be over 1,000 lines of source code that you write in some combination of Java, C, and C++. Note that learning a new programming language or development environment does not contribute to the "significance" of the project for the purposes of this course. You should already be familiar with the development environment you will use before you register for this course.

There are sections with more information on [ Picking a Project ] and [ Project Requirements ] later in this document.

There are no class meetings for this course. Each student works individually with an advisor (typically by email) to plan and implement his or her own project. Dr. Vickery acts as the default advisor for all students registered for CS-731 in the Fall 2000 term. A student may also arrange to do a project under the supervision of another faculty member, for example if the project is to be done in the context of a research program. But the requirements for the course described below (a written project proposal and a written development plan) apply to everyone regardless of who the student's advisor is.

Milestones

In keeping with standard software engineering practice, each project must proceed through a well-defined sequence of stages over the course of the semester. In particular, all projects must meet the following milestones, in the order indicated:
  1. Approval of a Project Proposal
  2. Approval of a Development Plan
  3. Code Completion
  4. Project Submission
Each of these milestones may require a number of iterations in which you submit a draft version of your work and make revisions based on feedback from your advisor.

Each of these four milestones is described more fully in the sections below.

Project Proposal

Deliverable: A document, one page or less, which describes the nature of the project you want to do.

This milestone should be completed early, typically by the end of the second week of the semester.

At this stage, you are simply deciding what your project will be. If you already have an idea for a project, you can present it to your advisor, and he or she will give you feedback on its suitability for this course. The [ Project Requirements ] section below will give you an idea of what makes a project suitable or not. If you don't know what you want to do yet, it's a good idea to come up with some thoughts about what kind of software you are interested in writing, even if you aren't ready to be concrete yet. One way to approach this is to think of a program that you would like to have but that isn't available (or costs too much).  There are some ideas for projects in the section Picking a Project below.

Proposal Format

Put a descriptive title for your project, centered, at the top of the page. Put your name, also centered, directly under the title, and put the date of your proposal, also centered, directly under that. As you submit revised versions of your proposal, be sure to update the date for each one.

The body of the proposal has three sections: Project Summary, Development Environment, and Project Evaluation. Each section should have a heading followed by a paragraph or two of information.

The Project Summary is where you describe what your project will do. While it would be appropriate to tell why you think the project will be fun or interesting to work on, you don't have to "sell" it to anyone. After all, this is an academic exercise, not a commercial product you are doing.

In the Development Environment section, tell what development tools and platform you intend to use. You are expected to write the code for your project yourself rather than rely on code generated by a development tool or "wizard." If you are going to reuse existing code or if some of the code for your project will be generated automatically, make it clear what code this will be and how it will relate to your own code.

The Evaluation section is where you describe how the final program will be evaluated. If the program is a simple stand-alone application you might not have anything special to say here, and this section can be omitted. But if your project requires a particular network setup or anything out of the ordinary in order to test and evaluate it, mention those things here.

Submit your project proposal and development plan as word processor documents (no viruses!). Do not submit these documents as web pages.

Development Plan

Deliverable: A document that tells how you are going to develop and test your project.

Once your proposal has been approved, you are to write a development plan that tells how you are going to code and test your project. Because projects for this course are "significant," you cannot just write all the code, test it, and hand it in. Rather, you will need to develop the program systematically. A good development plan is one that breaks the project down into easily debugged pieces of code and that provides a logical sequence for writing the pieces so that you can verify that all the code you have written so far is working correctly at each step.

Developmant Plan Format

The development plan document starts with the project title, your name, and the date, just like the Project Proposal. The body of the document consists of a numbered sequence of headings, one for each step to be followed in developing the project. Most steps will have a subheading for a use case, which is a version of the program that can be run and tested. Use cases should be numbered sequentially throughout the docuement. For example:

    Step 1
    Step 2
      Use Case 1
    Step 3
      Use Case 2
    etc.
Each development step should have its own descriptive name, and a paragraph telling what you will do for that step. It should be clear how the step contributes to the overall development of the program, and the sequence of development steps must make sense logically.

Use cases do not need names the way development steps do. Just write a paragraph for each use case that describes a working program that implements some subset of the overall project's functionality. For example, the first use case might display the user interface for the project with none of the user controls actually doing anything yet, and other use cases could then make the various controls do whatever they are supposed to to.

Here is a [ sample development plan ] that shows this structure.

Incorporating Throwaway Code

Your development plan might include some steps in you which write code that you will end up discarding by the time the project is finished. This "throwaway code" generally falls into one of the following three categories:
  1. Prototypes. Sometimes you know what you want part of your project to do, but you don't know which of several approaches to take. A prototype is a sample program that lets you investigate how something works in order to decide just how you want to proceed in the actual project. You might use prototypes to get a quick look at user interface options, or to help choose among communication options, for example. You might reuse some of your prototype's code in the actual project, but most of it gets thrown away.
  2. Stubs. A stub is a piece of code that implements an interface without actually doing the work a real method or class would do. An example of a useful stub would be when you are developing the user interface and want to make sure the correct processing routines (callback methods) are called, but haven't written the actual processing code yet. You can write stubs that have the proper method names, receive the proper number and types of parameters, but which do no actual processing before returning a value of the proper type. Later development steps would "flesh out" these stubs to include their full functionality. But as stubs, they let you test that your user interface (for example) is working correctly. Stubs are associated with a top-down development style, which is the one that will be appropriate for most projects.
  3. Drivers. A driver is just the opposite of a stub; it is code that you write for testing a class or method before you write the actual part of the program that will use that class or method. The reason for drivers can be because you are doing a bottom-up design, but that is generally not a good idea. More likely, you will write a driver when you want to generate test cases automatically for your methods and classes, and your application's user interface would make the process of running all the tests too tedious.
Be sure you indicate clearly what throwaway code you are including in the various steps of your development plan.

Code Completion

Deliverables: Source code for all the use cases listed in the Development Plan.

The code must be structured as an appropriate set of source modules. These modules will correspond to functional or structural elements of the project, not to use cases. A use case will normally add functionality to one or more existing modules.

As you complete each use case, test to make sure it operates properly, and then save the source code for that case. (You can do this systematically by using a version control system such as RCS, which is available for both the Solaris and PC platforms.) You are to submit the first few use cases as they are completed in order to verify that the project is on the right track. At some point your advisor will probably give you permission to develop succeeding use cases without waiting for each one to be approved. But until that happens you must not "work ahead" because your advisor might require changes that would affect later development steps.

Coding Guidelines

All code must be commented in a way that makes its structure, organization, and logic easy to understand.

For C and C++ code , you should follow the [ coding guidelines given here ]. For Java, write your comments in standard javdoc format, as described in the "tools" documentation of Sun's Java Development Kit (JDK). Javadoc comments for classes must include @author and @version tags (use the use case number as the version number), and javadoc comments for methods must include @param, @return, and @throws tags as appropriate.

Whatever language you use, be sure each source file contains your name and that each class and function begins with a suitable comment block that has some sort of separator line to make it easy to find.

All code must adhere to the following formatting rules:

Project Submission

Deliverables: Documentation and Source Code for the completed project.

In addition to the source code for the project, submit the following additional documentation items:

  1. Code Documentation. Provide a list with the names of all the source module files and any auxiliary files that you are submitting. For each file, tell how it fits into the overall structure of the project.
  2. User Documentation. Supply information that tells people how to use the program(s) that make up the project. This information may take the form of a user's manual or online help, which may either be integrated with the program(s) or separate, such as UNIX-style man pages or HTML Web pages. You need to supply user documentation only for the complete project, not for individual use cases.
  3. Management Documentation. Provide written information that tells how to build and install the software.
In addition, submit final versions of your Project Proposal and Development Plan documents if they have changed since being approved by your advisor.

Picking a Project

Some examples of projects ideas are: Note that there is no requirement for your project to be novel. Just because something has been done before doesn't mean that doing it again wouldn't be an acceptable project. But you have to write your own code!

If you don't have an idea for a project yet, talk to your advisor about it.

Project Requirements

Grading Criteria

The project proposal and development plan will be evaluated for content, structure, and clarity of writing. The project itself will be evaluated on the basis of its design, how well it works, how clearly it is coded, and how well it is documented.

Last Modified: June 16, 2000