CSC148H  Summer 1996

Comments from the markers of Assignment 3.

	Karen Reid and Adley Lo marked the assignment.

	If you have questions about how your assignment was marked,
	you can try to find them, or just see your instructor.

-------------------------------------------------------------------------

Program:  (things that lost you marks)
--------

Module data structure: Some (All) of the data structures moved out 
to the main program.

Module operations: Too much burden put on the main program; data
structures should be manipulated inside the modules.  Most of the
operations can be done inside a module, or a new module can be used to
do the user interface stuff.
(somebody didn't even a write module.)

Style: magic constants; variable names that are not descriptive;
code that is too compact (can't see it clearly); exporting constants which
are not used outside the module, etc.

Comments: A few people didn't have clear comments.

Testing: Not descriptive  (please describe your tests).


Report
------

1.  I was surprised by the number of sloppily written reports.  You *must*
proofread your work, use proper punctuation, grammar and spelling.  

2.  A suggestion for organizing your report:  Each section (module, main, etc.)
should have a heading (title).  Each idea (e.g. description of a procedure) 
should be in a separate paragraph.  Make use of lists (as I have done in
my set of comments) to write about things that have several steps, or to
highlight a set of points.

3.  The second biggest problem, was that many people explained how the card 
trick worked rather than explaining how they implemented the card trick.  

4.  Words or phrases to watch out for:  
	- certain, as in "certain procedures".   The point of a report is
	  to explain which procedures.
	- specified - Make sure you describe the specification.
	- abbreviations - We often use abbreviations in programming for
	  variable and procedure names.  When you write about your program
	  do not use abbreviations to describe it.  For example, you would
	  say that your procedure BinSearch (use the names as they are in
	  the code) implement a binary search algorithm, not a bin search
	  algorithm.
	- linked list not link list!
	      ^^

4. Module:
  The module section, should contain descriptions of each data structure, 
procedure, and function.  Describing a procedure means explaining how it
does the operation it implements.  For example, many people said that their
Pickup procedure rearranged the columns in the "specified order."  What
is the specified order?  How does Pickup rearrange columns?

  A picture of your data structure, along with type definitions really
helps to clarify your implementation.  When you have a picture, you can
refer to it in your descriptions of the rest of the module.  (A data structure
is not a type definition or a pointer, it is a linked list, stack, queue,
array...)

5. Main:
  The section describing the main program should include which procedures 
are called and when.  It is not enough simply to explain the trick.  

6. Flexibility:
  This section was generally well done.

7.  Testing:
   It is not sufficient to say, "I tested my program many times and it works." 
The purpose of this section is to convince the reader that your program works.
Furthermore, you must say more than, "I've tested it on the following set
of cases."  It is important to say what the result of the tests was.

   The testing of this program is a bit tricky, partly because it is pretty
easy to make the program work.  How do you know that it does work under
all circumstances?  You look at the cards when they are first dealt (assuming
DeckofCards works correctly), and compare them to the set of cards as they
are displayed on the screen after each iteration.  If they are the same
set of cards, and each card (not just the one the user has chosen) is in
the correct place after each iteration, then the program works.  This
method of testing is called visual inspection.

   Only two kinds of input could cause problems: the user gives an invalid
column number (I think everyone handled this well), or the user lies and
clicks on the wrong column.  There is nothing your program can do about
the second problem.  The final card displayed by the program will not be
the one the user expects.


Comments about the analysis section:
-----------------------------------

   We were looking for two things: the complexity analysis of each
   operation (big-Oh notation), and a comparison between the different
   implementations, in both their runtime requirements and space
   requirements.   

Common mistakes:
  - using terms like slower, faster, tedious, easy, hard, slightly without
    giving more concrete definition of how long the operation takes to run.
    O(n) is not necessarily tedious.
  - assuming that because the code will be complicated to write, the
    runtime will be long (or tedious).
  - not making a clear argument.  For example the statement "linked lists
    take more space than arrays" is not true in general.  The statement
    "arrays take more space than linked lists because arrays waste space"
    is also not true in general.
  - not realizing that the number of cities or the number of members in a
    city is not really O(n) even though O(n) is an upper bound on the
    number of cities or number of members in a city.