A Guide to Writing and Submitting Assignments

. CMPT 102

M.S. Drew

A Guide to Writing and Submitting Assignments

INTRODUCTION

This list of suggestions is online at .

Assignments must be submitted on the due dates listed in the semester handout for the course, by 10:30 AM, in the correct hand-in box (the one for our course) near the elevator in ASB.

I want to make some suggestions on how to have your assignment easy to identify. There are lots of students and lots of assignments, and it would be good to be able to figure out whose this assignment is! Hand in your assignment on time to the proper hand-in box, near the elevator opposite the main CMPT office.

Put your assignment in an 8.5 X 11 Duo-Tang folder, containing the following five sections:

1.

FRONT COVER LABEL - the front cover label of the folder must have the following

information:

a. your full name with the surname underlined

b. the language you are taking

c. the group you are in (see preregistration booklet)

2. TITLE PAGE

a.

assignment number - e.g. Assignment 8

b. your name e.g. J.A. Smith, Student No. 65000-0000

c.

class ? i.e., CMPT 102 C-Programming

3. USER DOCUMENTATION 1

The user documentation consists of a statement of the user purpose - what the program does, stated in every-day, non-coding language - and a layout showing a sample input and a sample output.

Consider the user: - what does s/he need to know? What does s/he want from the program? Most certainly, s/he will not want to read large amounts of information about the coding, but will want a concise description of what goes into the program, and what comes out.

User Documentation should contain:

a. TITLE. Give your program a name representative of what it does.

b. ORIGIN. Say who wrote it, when and where.

c. PURPOSE.

d. SAMPLE INPUT.

e. SAMPLE OUTPUT.

f. TEST RUNS.

g. SPECIAL RESTRICTIONS. Describe them briefly, for example, does your program read all 80 columns, or only 60 or 72? Will your program handle more than one set of data on a given run?

h. METHOD. Briefly mention any special algorithms used. Give formulae which are not common knowledge.

i. REFERENCES. Give the source of your algorithm or formulae. (This information is usually only necessary for original programs).

4. PSEUDOCODE

5. PROGRAMMER DOCUMENTATION AND COMPUTER OUTPUT.

Your program should have comments in it, similar to those of Assignment 1. Every group of statements corresponding to a "top-level" operation should be preceded by a comment, but other than that, comments should be few. Here's a hint: good programmers plan on paper first. Your pseudocode is your plan. Statements in your pseudocode can evolve into comments in your code!

a. The programmer documentation will explain everything a programmer needs to know about the program

b. If possible, attach your Unix I.D. to your printout: if it happens that your laser printer output comes without an I.D. page, go ahead and hand it in as is.

Make sure you have checked the assignment for test data and modifications before beginning any assignment.

2

Remember: ? no C in the User Documentation. ? explain what it is that you are doing, for a U S E R, i.e., someone who knows no programming. "Iteration," "initialize," etc., are meaningless terms to the user, although the user does know science. Therefore, the data type "char *" etc., is unknown, but you should explain what you're doing mathematically, either in the Purpose section or the Method section. ? using pen and paper, rather than typing up everything is just fine (provided I can read it) ? a complete set of Sample I/O is mandatory, even if it just involves using cut-and-paste from a copy of the assignment; otherwise your intentions are not clear enough. ? what does the user need to know? What must be done, what must not be done, what will normally happen, what will happen if data is input improperly, etc.? Also, if possible try to indicate whether data items should be float or int by showing them with or without fractional parts. Make sure you have checked the Assignment for test data and modifications before

beginning any assignment. If you have any difficulty understanding any of these directions, ask myself or the TA to

explain them in more detail. It will save you time and worry.

3

Example Assignment Writeup of Assignment 1

This Appendix contains the writeup of a completed assignment using Assignment 1 as an example. Before going on to the example, it is important that you understand the difference between "user" and "programmer" documentation.

User Documentation The user documentation section includes the "User Purpose," "Sample Input," and "Sample

Output." User documentation is designed for the benefit of the user. It is quite conceivable that this person may not have any knowledge of computing and computing programs. Therefore, a detailed explanation of what the program does, what the input should be, and what the output will look like is necessary here. Documentation should be brief and NOT C ORIENTED, yet should contain a good explanation of the program and how to use it.

Programmer Documentation The programmer documentation is intended to describe the methods used in coding the

program. It consists of the comments inserted in the program, the test runs, and the pseudocode. In addition to providing a short TECHNICAL explanation of what the program does, this type of documentation includes step by step explanations of each section of code, by means of program comments. If changes need to be made at some time in the future, these comments are of invaluable assistance. Take another look at Figure I.0 to see how a comment block at the beginning of the program describes the program, and a dictionary of variable names provides useful information to another programmer reading your program, or to yourself at a future time.

All programmer documentation should be short and to the point. A good rule is that a comment block should be used to replace a segment of code for a programmer who chooses to simply read the comments rather than the code itself.

4

Example Writeup for Assignments

Starting with a Title Page, here follows a complete descriptive example of what you hand in for an assignment.

CMPT 102 Assignment 0 J.A. Smith, 65000-0000 September 10, l965 C-Programming

5

 ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download