CPSC 217: Assignment 2  ("The Dungeon of Doom": the Inner Sanctum)

Due at 4 PM. For assignment due dates see the main schedule on the course webpage. The program must be written and run under python version 3.X.

Assignment difficulty

Students may find assignments more challenging than they first thought. It's best to start work as early as possible. Tips in the very first lecture were provided but here's two reminders: 1) work through the lecture and tutorial material before looking in detail at the assignments 2) start work as soon as possible. If you find you cannot complete an assignment before the due date then you will not be granted an extension.

Note: it is not sufficient to just implement a working program and expect full credit. This requirement exists so you implement your solution in the correct way using good design principles and you apply the necessary concepts. Even if your program is fully working and the program is not designed or implemented as specified in the assignment description (e.g. poor variable names used, named constants, functions not implemented appropriately or insufficiently etc.) then you will not be awarded full credit.

Your program must be decomposed properly into functions. One way of decomposing your program is to include all the instructions needed for a room as a single function (or you can subdivide things further i.e. the code for a room is split between multiple functions). Because there are three rooms that will mean that your program will consist of at least 4 functions (1 per room plus a starting function). You may be able to subdivide your program using an alternate approach to writing 1 function per room but your program must follow [principles of good design for using functions].

New Concepts to be applied for the assignment

• Decomposing a problem into functions (includes concepts such as parameter passing, return values, local variables/scope).
• If you want credit for your work: Do not use any pre-created functions/methods unless you are given explicit permission to do so. [General_use_of_pre-created_Python_libraries] Using a function that someone else has wrote e.g. random.randrange() is not the same as your defining a new function. You will have to define at least four new functions whose code bodies that must be written by you.

Only new concepts that need to be applied in the assignment are listed, concepts previously applied in other assignments may need to used in the implementation of your solution.

Critical design requirements

All instructions must be enclosed within the body of a function, at least 4 functions must be properly defined and follow [good design principles for functions]. No global variables  may be employed. The exceptions to having statements outside of a function: import statements (not really needed for this assignment), the creation of global constants (e.g. ATTIC = 1), a global debugging flag (if you choose to employ one, not mandatory for this assignment) and the call to the initial start or main function.

• You will be penalized heavily if functions are not used or improperly used.

  • No functions or a single function employed then the max assignment grade = 1.0 grade points
  • Two functions properly implemented then the max assignment grade = 2.0 grade points
  • Three functions properly implemented then the max assignment grade = 3.0 grade points
  • In order to qualify as properly implemented the function must include functionality that is appropriate to that function (e.g. anything related to the attic should not be implemented in a function that includes functionality for the bedroom) and not an empty (e.g. it just includes a pass instruction) or a token implementation (e.g. a few output statements or declarations for things such as variables or constants).

• In a similar fashion you will be penalized heavily if you define or use global variables (global constants are okay, if you don't know the difference between constants and variables then refer to the "Intro programming" lectures covered at the start of the term).

  • When any global variables (not a debugging flag and not constants) are employed then you will be penalized a full grade point (1.0). To rephrase: This penalty applies if you define one or more global variable(s).

  • Example:
    location = "bedroom"  #Global declared
    def processBedroom():
        if (location == "bedroom"):  #Global referred to in the function.
            #Etc.

• What happens if you ignore both of these requirements (sufficient/proper use of functions and the prohibition on the use of global variables).
  • If you define no functions or just a single function and your program includes any global variables then you will be awarded no credit for this assignment. (It might seem 'harsh' but the main learning objective of this assignment is to learn how to implement a program with functions so really aren't getting anything out of this assignment by just writing yet another program that doesn't properly employ functions.)
• The function-related & global variable penalties are applied before other style penalties but the lowest grade that may be awarded is a GPA of 0 (no negative scores will be awarded).
• Why do we include such 'strict' requirements? Contrary to some student rumors it is not the case that penalties exist in order to "curve the grades down" or to only allow a certain number of students to pass the course. Besides learning the mechanics of defining and calling functions you need to use them properly. For instance if you are enrolled in a course where you write short stories they should of course be grammatically correct. But just being grammatically correct is not sufficient. Nor is it sufficient if you employ writing tools such as metaphors, characters and a plot if those tools aren't used properly e.g. the characters all cliched or 2-Dimensional, the metaphors are inappropriate. Although you don't need to know the elements of a poor/well written story for this lecture: [here's a reference just because some students will ask for examples]. Because the penalties are quite strict then typically most/all (hopefully the latter) students will implement their solutions in the correct fashion.  I can recall from my experience as a former student (as well as noticing the behaviors of my classmates) that if an instructor does not enforce design/style requirements in the grading that many students would sometimes ignore good design principles and focus only on program functionality.

  As you can see in the official University of Calendar description CPSC 217 is a procedural programming (decomposing a program into functions). If you by the end of the term don't implement your programs using functions or you don't do so properly (following commonly accepted good style requirements) then you have missed the point of the whole course. So the restrictions help ensure that students can only attain a certain grade if they can demonstrate this. Note: these requirements don't mean that you have implemented all the features correctly. Instead it just shows that you will apply the key course concepts properly.

Functional requirements (working features of your program, for the marks allocated for each feature see the marking spreadsheet):

Living room contents: a pot of soil, stairs going up, a dark entranceway, a ball of a string

(Actions you must implement for the living room).

• Viewing the pot of soil: 1) Default state when viewed, it looks dry  2) After it's been fertilized by the mouse (from the bedroom), when the player views the pot again a vine will grow that takes the player to paradise (game won and the program ends).
• Stairs going up: takes the player to the attic.
• Dark entranceway: takes the player into the bedroom.
• Ball of string: the player can pick up this object. There is only one ball of string, once picked up the string should not appear again in this room.

Attic contents: a tiny hole in the floor, an unlimited supply of cheese, stairs going down.

(Actions you must implement for the attic).

• Hole: 1) player can pick up some cheese and try to drop it down the hole, the game indicates that the cheese is too big (this won't have any effect on the player's inventory because the player will not keep the cheese after trying to drop it down the hole)  2) If the player has the string then a new option is provided which is to drop the string down the hole. When this occurs the string should be removed from the player's inventory (the string doesn't reappear anywhere in the game, nor does the option to drop the string down the hole appear again in this room). The effect of dropping the string down the hole will be seen in bedroom.
• Cheese: player can pick some up, the supply of cheese is unlimited so repeatedly picking up the cheese won't diminish the supply (or change the room description). However the game should track that if the player is carrying any cheese (this will allow the player to feed the mouse this cheese in the bedroom). And the inventory will only track the cheese as being in the player's inventory if the player explicitly picks it up with the intention of keeping it (and not just when the player tries to drop it down the hole and then sets it down again).
• Stairs going down: takes the player back down to the living room.

Bedroom contents: a tomcat which is intently watching a mouse hole (default), mouse (after the cat leaves).

(Actions you must implement for the bed room).

• Tomcat: when the player isn't carrying the string no interaction is displayed. When the player is carrying the string then there is a option to use the string to play with the cat. The result is the cat looks briefly at the player and then goes back to watching the mouse hole (the motion isn't enough to greatly distract the cat).
• Mouse: after the player drops the string down the hole from the attic the large motion distracts the cat sufficiently enough to leave the room and he takes the string with him. The mouse then comes out of its hole. The game will then indicate that the mouse is in the room. If the player is not carrying any cheese then the game will only indicate that there is a mouse in the room but there is not opportunity to interact with it. Only if the player is carrying some cheese will the game display an option to feed the cheese to the mouse. When this occurs the mouse will leave the room and fertilize the pot of soil. (The vine will grow and the player will win the game when the soil is viewed again from the living room). After fertilizing the soil the mouse will return to the room so there is the possibility of the player repeatedly feeding the mouse (the amount feed to the mouse is negligible so it doesn't change the amount carried by the player i.e. the player can still feed the mouse without picking up more cheese from the attic). 
  • Recap: the game provides an option to feed the mouse only if the player ever picked up any cheese and if the cat has been replaced with a mouse. Each time the mouse has been fed then the program doesn't check/change the player's inventory.
• Dark entranceway: takes the player into the living room.

As was the case with the previous assignment each room will provide a description of the contents, display a menu of options (which varies depending upon the state of the game), get and error check the player's selection and display the menu and description for the room as long as the player remains in that location.

Game walkthrough: because this program is more complex than the previous one the above summary map cannot provide details of what the player needs to do in order to win the game. Similar to an actual game a text step-by-step walkthrough specifies what's needed to win the game.

1. Living room: Pick up the ball of string.
2. Living room: go up the stairs to the attic.
3. Attic: drop the string down the hole.
4. Attic: pick up some cheese.
5. Attic: go down the stairs back to the living room.
6. Living room: go through the dark entranceway to the bedroom.
7. Bedroom: Feed the cheese to the mouse.
8. Bedroom: go through the dark entranceway back to the living room.
9. Living room: view the pot of soil (and win the game).

Overall program design

function attic()

Do while (player is in the attic)

Display options for attic

Get player's selection

Take appropriate action based upon the selection

End while

end function

 

function bed room()

Do while (player is in the bed room)

Display options for bed room

Get player's selection

Take appropriate action based upon the selection

End while

end function

 

function living room()

Do while (player is in the living room)

Display options for living room

Get player's selection

Take appropriate action based upon the selection

End while

end function

 

function start()

    Do while (game has not yet been won) #Main program loop

        if (location is living room) then

            call function for living room

        end if

        else if (location is attic) then

            call function for attic

        end if

        if (location is bed room) then

            call function for bed room

        end if

    End while

     Run end game instructions

end function

Sample outputs of this program:

You can find sample outputs of my solution to this assignment in a link to this [Link to the folder containing outputs].

In addition to grading on whether the above functionality was correctly implemented TAs will also look at documentation and style.

Non-functional assignment requirements (style and documentation).

General programming style requirements (-0.1 penalty for each  violation of a category 7 categories of penalties means a maximum penalty of -0.7 will be applied)

• #1: Naming conventions: You should employ good naming conventions for identifiers (variables, constants and even function names) as covered in the "Intro to programming" and "Functional decomposition" sections of the course. Also note there is a specific name that you should give to the file containing your program which is specified under the [marking and grading section].
• #2: Named constants should be used as appropriate (and if they aren't a penalty will be incurred).

	Yes do it this way!	No. Not this way!
	LEFT = 0 RIGHT = 1 CENTER = 2 if (silverLockPosition == RIGHT):	if (silverLockPosition == 0): #What does 0 stand for???

• #3: The program code should have appropriate white space (specified in the "Intro to programming lecture") and alignment (specified throughout the lecture notes).
• #4: Code is self documenting e.g. Clear expressions (e.g. mathematical, Boolean). Expressions should be clear and simple (break up or restructure complex expressions). Good variable names and the use of named constants are examples of writing self documenting code but naming conventions is important enough to warrant a separate category.
• #5: Your program should follow the 6 rules of thumb for designing user friendly software (distilled from Jakob Nielsen's 10 usability heuristics - see the Usability Heuristics in the [Part III of the looping/repetition notes]). e.g. good error handling (such as prompts to the user to enter the required information clearly indicate what is required, good error messages/error handling should be provided for erroneous input) minimizing the user's memory load, being consistent, making the interactions with the program (the "dialog") as simple and as natural as possible, providing clearly marked exits & providing feedback as appropriate. This includes but is not limited to having the menu selections for choosing the action for each room being intuitive.
• #6: Of course if a student implements an extreme case of inefficient code (e.g. multiple loops or branches are used when one will do) then penalties may be applied but this is generally rare i.e. it has to be really bad to warrant a penalty.
• #7: The program should not employ abnormal termination mechanisms e.g. something such as a 'break' instruction for loops or calls to the  'exit()', 'quit()' functions anywhere in the program.

Having at least one violation in one of the above general style requirements will result in -0.1 penalty to marking. Multiple violations in one category still results in a single penalty (e.g. 3 bad variable names will still result in a -0.1 penalty). However violations between categories will result in cumulative penalties (e.g. a program that includes poor variable names, messy program layout and poor error handling will receive a -0.3 penalty)

Function specific style requirements (principles of good design for functions) -0.2 penalty will be applied for each of the 3 function specific style requirements that have been violated.

• #1: Functions are one screen in length (normal screen 40 lines max of code (the count excludes white space and documentation).
• #2: Functions implement one well defined task (e.g. processLivingRoomCommands vs. processlivingRoomRunIntroductionRunConclusion).
• #3: Code in one function is not duplicated in another function (not in the notes but this is just common sense that you don't write two functions where there's overlapping code - the overlap should likely be taken out of both functions and moved to another separate function). In this assignment there may appear to be some overlap (e.g. each room displays a menu of options but the specific options displayed will not be identical.
• Violating any of the function specific style requirements will result in a -0.2 penalty for a violation in each of the 3 categories. E.g. a program that includes a function that exceeds the maximum length and implements two or more tasks would incur a -0.4 penalty.

Documentation requirements:

• Header documentation: This should be specified in the header of the program (very top of your program in the form of Python documentation). The basics of documentation were covered in the "Intro to programming" section of the course.
  • Identifying information: All assignments should include contact information (full name, student ID number and tutorial section [Here's a link if you don't know how to find this information]) at the very top of your program.
  • Program version. (version date or version number).
    • Under the version you should specify which assignment features were implemented in that version as specified in the [last part of the "Intro to programming"] section of the course.
  • Any program limitations or weaknesses.

• New documentation requirement starting with A2 and applies to all successive assignments: Just before the header definition of the function ["In line documentation"]: list the features of the assignment (e.g. checking list bounds, displaying the list etc.) that were implemented in a particular function, the return type(s) as well as the type(s) of the arguments. Greater details are provided in the functional decomposition lectures.

How to do determine 'how you did' on an assignment?

Program functionality (implementing working program features)

• Test your program: Because the [marking key] is posted ahead of time if you test your program thoroughly before submitting the final version then you should get a pretty clear idea of "how you will do".

Style and documentation (non-functional assignment requirements)

• Style and documentation requirements were introduced early in the semester in the  [last part of the "Intro to programming"] section of the course. Additional requirements may be added as new sections are covered (e.g. documenting functions that you write your yourself). Each assignment will specify these requirements specific [under the non -functional assignment requirements (style and documentation). ] to that graded component. Again you should refer to the [marking key] in order to determine how style and documentation will affect grading for a particular assignment.

Marking and grading

• Naming the file containing your program: You must save your program in a file called "doom2.py". Failing to use this exact name will affect your grade by the amount specified in the [marking key].
• What to submit: If your submission won't run using Python 3.x on any computer then it won't be awarded credit. It's up to you if you wish use a graphical program builder other than IDLE (or another development environment rather than a simple text editor) to write/run your programs but regardless you must submit your program in the form of a text ".py" file or files. Also if you run into problems using another editor then you may be "on your own" because we only have the ability to support one development tool which is IDLE.
  • All computer users: Be careful that you actually submit the file containing your program and not a related file, here's one example of a problem: operating systems sometimes create a "lock file" [Description of a lock file for Windows users] [Description for UNIX users - may apply to MAC-OS].
    • Tam's brief explanation of a lock file: These files are created when a file is being edited to prevent multiple users or programs from trying to edit that file. (Names of lock files typically include the file being edited but include a tilde character in the name e.g. the file being edited is 'a1.py' so the lock file is named '~a1.py'. Because the lock files do not contain the actual data take care that you don't accidentally submit the lock file instead of the file (some students have actually done this).
  • Windows users: take care that you don't accidentally submit a [shortcut to a file] instead of the actual file. (Check the file name and compare the file size to your original file. Simply downloading the shortcut file as a test won't work because that shortcut will work on your computer but not on anyone else's machine and this may mean your work won't be graded.)
  • MAC-users: this operating system has an equivalency to Windows shortcuts (e.g. symbolic links but since creating them is a little more involved, typing at a command line "ln -s <target file name>" it's less likely that this problem will come up).
• Before the due date, late assignments or components of assignments/assignment extensions: Due dates/due times are strict and extensions require documentation (e.g. a note from a medical doctor) in order to get permission from the [course instructor]. If/when permission is awarded for a late submission then I will let the marker know that the regular penalty will not be applied. When you ask for an extension you need to specify the name of the TA in the tutorial that you are officially registered. Alternate submission mechanisms to D2L (non exhaustive list of examples: email, uploads to cloud-based systems such as Google drive, time-stamps, TA memories) cannot be used as alternatives if you have forgotten to submit work or otherwise have not properly submitted into D2L. Only files submitted into D2L by the due date/time is what will be marked, everything else will be awarded no credit. The final cut off date after which full assignments will not be accepted is after the [maximum progressive penalty (listed below)] can be applied.
• Questions or concerns about grades after they have been released: Assignments will be marked by your tutorial instructor (the "Teaching Assistant" or "TA") in the [tutorial section] you are officially registered in. If you don't know which tutorial section you are officially registered in then you can find this information in the Student Center in the [PeopleSoft university portal]. When you have questions about marking this is the first person that you should be directing your questions towards.  If you still have question after you have talked to your TA, then you can of course talk to your [course (lecture) instructor] but please indicate in your email that you first contacted your TA before going into your concerns. 
• How you will be graded for full assignments. As mentioned, as well as being marked on whether "your program works" you will also be marked on non-functional requirements such as style and documentation. Like other full assignments, this one will include a separate [marking checklist]. Besides seeing your grade point in D2L you can also see the detailed feedback that your TA will enter for each student. You can access the grading sheet in D2L under Assessments->Dropbox and then clicking on the appropriate assignment link. If you still cannot find the grading sheet then here is a [help link]

Method of submission:

Reminder: You are to submit your assignment using D2L  Here's a UC-IT created [D2L help resource] . Make sure that you [check the contents of your submitted files] (e.g., is the file okay or was it corrupted, is it the correct version, it is the correct file etc.). It's your responsibility to do this! (Make sure that you submit your assignment with enough time before it comes due for you to do a check). If don't check and there were problems with the submission then you should not expect that you can "learn your lesson" and simply resubmit Whatever you submitted into D2L by the final due date (and due time) is what will be marked.

D2L configuration for this course

• Do not use compression utilities (such as zip) or archiving utilities (such as tar) otherwise your submission may not be marked. The space savings in D2L is not worth the extra time required by the marker to process each submission.
• How often can you submit: Multiple submissions are allowed for this assignment: You can (and really should) submit work as many times as you wish before the due date. However only the latest file submitted is the one that will be marked, everything else will be ignored (because it is not fair to your marker to sort through multiple versions of your files).
• What to submit: Python programs only (file name ends in .py)  Any other type of file will be rejected by D2L.

General use of pre-created Python libraries:

Unless otherwise told you are to write the code yourself and not use any pre-created functions (or methods). For most assignments the usual acceptable functions include: print(), input() and the 'conversion' functions such as int(), float(), str(), range() - the latter is actually not actually a function but a composite type such as string or a list but it looks like a function. Look at the particular assignment description for a list of other functions/methods that you are allowed to use and still get credit in an assignment submission. If it's not listed then you should assume that you won't be able use the function and still be awarded credit.

^{1 Choose your own adventure. Rather than passively reading through a fixed story written by the author a choose your own adventure puts you in the role of the story's protagonist whereby you can determine the outcome of the story by choosing at various points the direction that will be taken by the story.}