CS224 -- Spring 2012

Project #1

Assembly Language Programming

Preliminary Design Report

Due Date: Wednesday March 7th, between 13:05 and 13:25, to be submitted into the box outside EA-128.  No early submissions (before 13:05) will be accepted. Late submissions (after 13:25) will be penalized quite heavily, so make every effort to get your report in on time, by the deadline! Groups should prepare and submit 3 copies of their Preliminary Design Report. Note that the person submitting the reports can be a friend, it doesn’t have to be a group member—no one should miss their class because of turning in the Preliminary Design Reports.)

Submission Rule: Each group will submit 3 copies of the Preliminary Design Report (and should of course keep a fourth copy for themselves, in order to be able to continue work on the project).  The representative will submit the 3 copies of their own Preliminary Design Report to the box outside EA-128, then leave.

Pickup Rule: Each group will pick up 3 different reports, submitted by other groups, for them to peer-review for the next phase of the project, from the TA in EA-128, after 16:30 on Wednesday March 7^th. A representative of each group should come to EA-128, to pick up the reports for peer-reviewing and peer grading. All groups should pickup the reports they will peer-review between 16:30 and 17:20 on Wednesday.

Grading: The Preliminary Design Report is worth 25% of the overall project grade.  Grading will be based on the following: 

1.      Completeness--did your group do all that was required, did you adhere to the requirement specification completely, in every aspect? {Check the specification!}  

2.      Correctness/accuracy--did your group correctly understand and design the solutions needed for the 6 data structure utility routines? Did your group correctly model the 6 algorithms in high-level code (or pseudocode) and in intermediate-level pseudocode? Are there errors or omissions that need to be fixed?

3.      Understandability/readability/neatness--is the report and all its parts of good quality, neat and clean, easy to understand?

4.      Overall quality--what is the overall quality of the preliminary design work and its documentation?

Contents: The Preliminary Design Report will consist of a cover page, followed by a table of contents page, followed by the main body of the report, with each part beginning on a new page:

• Cover/title page, with course number, semester name and year, name of the document, group #, name/ID/phone/email/section listed for each group member, along with the signature in ink of each person to the Honor Pledge, and the submission date. (Note: reports must be signed, in blue or black ink only; missing signatures, or pencil signatures, will not be accepted.) Each group should use the cover page template given here, personalized for your group of course.

• Table of contents page, listing each section and subsection of the main report body, with the page number that the section and subsection begins on.

• The main body of the report containing 6 sections, each explaining one of the 6 data structure utilities (build, check, sort2list, etc).  Each section should begin on a new page.  For each section, there should be 3 parts, describing the utility in English, then at a high level (in HLL or high-level pseudocode), and then in intermediate-level pseudocode.  For each of the 6 sections, there should be 3 subsections, each beginning on a new page:

a) the verbal explanation of the utility (including what it does and how it does it) in clear understandable English, along with any figures needed to explain the concepts. The figures should be clear, and add to the reader’s understanding of how the utility does its work on the data structure. To help your English explanation, you should use pictures and figures. All the figures in this section should have a figure number, and a caption (e.g. "Figure 2: The cell-wall structure showing the energy transport openings") and should be referred to in the text at an appropriate point, by its figure number.  Figures always come after their reference in the text, not before. If at all possible, a figure should be on the same page as the first text reference to it.

b) the high-level code (written in C, C++, Java or high-level pseudocode) which describes the algorithm of the utility. The 6 utility routines should be written in well-structured self-documenting high-level language code (or high-level pseudocode). You should not include a “main” program, just the 6 callable subroutines, plus the headers described below. There should be lots of line-commenting in your high-level code, to make it easy to understand. The line comments should be formatted in proper alignment. Each of the 6 procedures must be preceded by an explanatory header, which contains a description of the algorithm and lists and explains all the variables and data structures used in the procedure. In other words, the high-level code should be self-documenting, meaning that it is understandable to others because of the 6 procedure headers, code comments (found throughout the code), well-chosen names (for variables, functions, etc), and spacing and alignment for readability.

c) the “explanation” of the utility in intermediate-level pseudocode.  In other words, there should be a pseudocode implementation of the utility, which includes an explanatory header and comments.  As with any code, the pseudocode should be self-documenting, which means it contains an explanatory header, lots of comments next to the instructions, and use of meaningful symbols and variable names.  The pseudocode should make clear the algorithm used, i.e. how the utility will be realized.  The semantic level of the pseudocode should be intermediate-level, between the HLL and assembly language, so that it can serve as a transition step before writing the assembly code.  You should follow the given syntax guide for pseudocode; this will help to standardize the pseudocodes.  The pseudocode should use white space and formatting to enhance readability and understandability.  The intermediate-level pseudocode is not real code from MIPS or any other language—it is described with examples in the Pseudocode Guide.

Format: The report should be typed, and printed out on a high quality printer.  Its appearance should be professional, clean and neat throughout. It should be stapled in the upper left-hand corner, with the sections arranged in the order given (above) and submitted without a folder. Each of the 18 subsections in the body of the report should begin at the top of a new page, and should have a section number which is consistent, and a heading or title. An example of a very good Preliminary Design Report from a previous semester, is given as a guide to help you.