CS712/CS812
Project Guidelines
Spring 2001

Assignments

Project phase assignments will be made no later than the Wednesday of the first week of the phase. Students can request a particular assignment by contacting me prior to the start of the phase. Students are responsible for working with me to nail down the details of the assignment, to remove any ambiguity about what is required to be completed, ideally prior to the end of the work day on the Friday of the first week of the phase.

Submissions

Each project phase submission must include the following items:

modified source code;
a detailed test plan and the test results;
test files, test scripts and directions on how to use them;
and, a self-evaluation.

The test plan should state which cases are being tested and cite the test file that tests each case. The test plan should also cite the relevant sections of the ANSI standard. You are strongly encouraged to solicit help from classmates in the development of test plans and in performing the actual testing. Testing should include code reviews by knowledgeable people other than the author of the code.

You should have a draft test plan written by the half-way point of the phase. This draft plan should be in your possession at every class meeting and I reserve the right to ask you to present it in class with no prior warning.

Just as you should consider your test plan to be a "public" document, you should also write your code assuming I, and all the other students, are constantly looking over your shoulder. You should be prepared at a moment's notice to review your code with me, with small groups of students, or with the whole class. This is particularly true when the code is still under construction.

The purpose of this "openness" is not to embarrass people, but rather to improve the quality of the code produced by the project. In reality high-quality code is not produced in isolation but rather is produced with the aid and support of your co-workers. So, "check your ego at the door" and be prepared to work as a team.

The test results are an addendum to the test plan and should state whether the test plan was fully followed or not. You should also list any outstanding bugs that have not been fixed prior to the submission. Provide your analysis of these remaining bugs. They may either be in your code or might indicate problems in pre-exisiting code.

The best approach to testing is to automate it as much as possible. Therefore, the use of scripts, to run the tests and evaluate the results, are strongly encouraged. This will make it easier for us to use the tests for regression testing throughout the semester. Students are encouraged to share their script skeletons. (That is, we will try to leverage any scripting expertise that we have among the students taking the class!)

The self-evaluation must be brutally honest. If the overall project is to succeed we must all be honest about the state of our work.

Evaluate your code. Does it conform to the coding conventions (see below)? Is it properly documented? Can it be easily read, understood and modified by other students? Is your code ready to be integrated with other students' code? What are the code's shortcomings? What would you do differently if you were to start again?
Evaluate your testing. Was your testing plan complete? If not, what are its shortcomings? What is your confidence level in the code if it becomes the "official" code to be used by the project? Are you willing to be responsible for fixing any remaining bugs in the code if the code is used by the project?
And, finally, the "bottom-line" question: Do you recommend that your code be chosen as the "official" code to be used by the project?

Both the test plan and the self-evaluation should be simple text files. However, these documents should have a heading indicating both the purpose of the document (i.e. a title) and the author. You should also write in complete sentences, use proper punctuation, and check your spelling. (That is, these documents are not to be dashed off at the last minute!)

Submissions should be performed electronically from a CIS Alpha. For example, to submit for phase1:
~cs712/bin/submit phase1 list of files to submit

Grading

Grades will be assigned to project submissions based upon 50% of the points being awarded for your implementation work and 50% of the points being awarded for testing.

Project assignments are due on the last day of each phase. Assignments may be handed in late at a penalty of 5% per day up to one week late. An assignment is not considered late unless turned in after 8am on the day after the due date.

The work you submit under your name should be substantially your own. You are encouraged to work with other students on the test plan and the testing. You are also encouraged to have other students review your code. However, the code you submit should have been written by you. Any collaboration during the coding must be explicitly approved by me in advance and must be documented in your self-evaluation. In particular, be very careful about collaborating with other students that have been assigned the exact same assignment. Inappropriate collaboration will result in severe penalties for all people involved.

Meetings Outside of Class

On occasion I may need to meet outside of class with individual students or with small groups of students. I will try to keep these meetings short and to a minimum, however.

Coding Conventions

The code you write should conform to the following conventions:

No tabs. They are evil!
Use two-space indentation.
Lines should be no longer than 80 characters.
Declare only one identifier (e.g. variable) per line.
Use Java-style names. charsPerLine rather than chars_per_line.
Use meaningful names.
Always use function prototypes.
Avoid long functions.
Function bodies should be well-commented. Something that is obvious to you in February may not be obvious to either you or me in April. Ask your code reviewers to review your comments.
Use symbolic constants when appropriate.
Always use { and }, and place them on separate lines. For example,
if (x == y) { ... }
Every file should begin with a comment to describe the purpose of the file. This comment should also include the name of the file.
Use blank lines to demarcate different sections of code.
Each function should have a header comment describing its purpose.
Avoid global variables. I need to approve each global variable that is visible across multiple files.
Use "static" to hide functions and global variables that do not need to be visible across multiple files.
All code should compile cleanly, with no warnings (unless I explicitly approve them).
Test all library calls (e.g. malloc) for failure.
Use the "message" module to report errors (both internal and user).

Last modified on January 18, 2001.