How to submit your homework assignments
All written assignments must be put in my mailbox (in the CS mail
room - CSB727) before the time the assignment is due (usually 5pm). I
check my mailbox shortly after the assignment is due and take out all
assignments. The room is open until 5, after that you can always
knock on the door.
All programming assignments should be submitted using my TURN_IN
script. If you type your written assignments, you can submit them
using the script, too.
To submit an assignment, you should call
/u/myros/commands/TURN_IN your_directory_name
Your assignment directory must have a README file containing your
writeup, or the script will reject the submission.
You can email your assignments to me tarred and gzipped if for some
reason you are unable to access the department network. However, this
should be done only under exceptional circumstances, and I must
receive the email before the deadline.
Written assignments submission requirements
You can either write or type your solutions to the homework, but
whatever you submit should be in easily readable form.
If you are writing the solutions, please write legibly, leaving enough space
between the lines to make it easy to read. If you have to cross out and
correct many things on the same page, or if you are writing with a pencil and
had to erase things several times, please re-write the page. Too many
deletions and corrections make everything very difficult to read.
If you are typing your solutions, please use a text processor which
supports subscripting, superscripting, and math symbols necessary to
use in the solutions. If you're using LaTeX, talk to me - I have a set
of pre-defined commands that can help you to do your typing more
efficiently.
Programming assignments submission requirements
For all programming assignments you submit must also have a writeup
accompanying them. Comments in the fine alone are not
sufficient. Depending on the complexity of the task, 25 to 45% of the
grade will be allocated for the writeup and programming style.
When grading, I will read your writeup first and attempt to test
your program on my test cases. I will then look at the code to check
the implementation. You will lose points if I spend too much time
either figuring out how to run it (which should be obvious from your
writeup) or how it works. I will give partial credit for programs
with some bugs, but only if the code is readable enough for me to
know what the bugs are.
Writeup
Please include the following in your writeup
- the names of all your program and data files, with short descriptions
of contents, if this is not evident from the names
- the names and types of arguments for functions I have to call to
test your program.
- General description of the algorithm. You do not have to include
the detailed descriptions of all the functions in your program, but
I must to be able to get a good idea of how your program works without going
through the code. This includes explaining design choices like storing
data in a hash table vs a list.
- The input and output data format, unless it is extremely simple
or described in detail in the assignment.
- Test examples to demonstrate that your program works and
that you understood the problem and thought about different possible
inputs. I have to be able to answer the question "If the program does
not work properly on my test data, in which cases it does work?."
- Special cases. In general, you can assume that you're given the
right type of argument - if you expect a list, you won't be given a
string. But you must be prepared to handle special cases such as an
empty list. In general, I do not care what your function does -
produces an error or returns some predefined value different from
normal cases, but you have to document it. The only unacceptable case
is causing stack overflow - your function should not be going into
infinite recursion on any data.
- Known problems. If your function has bugs you didn't have time to fix
- document them. You'll get more points than if I discover them myself.
- Answers to any questions asked in the assignment.
Also, if you're running out of time and cannot implement something,
describe in more detail how you would have done it - you may get
credit for this, too.
Programming Style
The bottom line here is, if I cannot read your code easily, or it does
something potentially dangerous, you lose points for programming
style. The most important guidelines, based on most frequent mistakes
people make, are below.
- All your functions must conform to the specifications in the
assignment. This means that you use the function names specified in
the assignment (if any), and both input and output value types must
be the same as specified in the assignment. If you want to use a
different data structure for optimization purposes, conversion
to/from the standard format should be provided.
- Follow the usual good style guidelines, which includes
comments or self-documenting variable names, and avoiding obscure
programming constructions. In particular, programming constructs that
make your code more difficult to read are
- General loop operator "DO" - use "DOLIST", "DOTIMES", "MAPCAR", or recursion
instead.
- Property lists.
- Progn. You should never need it. If you feel you need it with
"if", don't use if, use "cond" if you have 2 or more branches, and
"when" for a single branch.
- prog, go, tagbody and other goto-like constructs. goto is bad
in any language. It is next to unreadable in LISP in most cases, and
there are absolutely always better substitutes.
- return and return-from. They are OK in a small (just a couple of
lines) function. For larger functions, returns from the middle are
bad style even in procedural languages. In LISP, you're almost
always better off with recursion or filtering your results afterward.
- Indent your code appropriately, this makes a major difference in
readability of LISP code. The default indentation provided by emacs is
good. Look how examples in "Common
Lisp The Language" are formatted and use it as a guide.
- Declare all your variables. The global variables are declared
using "defvar" or "defparameter", and the locals are declared using
"let". You will lose points for undeclared variables, especially if it
interferes with global variables I set for testing. As in any
algorithm, you should only make the variables global if there are
good reasons for that, and motivate your decisions in the
algorithm. Tip To check for undeclared variables, do :cl
filename in allegro CL, it will compile the file and produce
warnings about "free references to variables".
- Don't replicate existing functions. Check the "Common Lisp The Language"
first. Lisp has an extensive library of functions to work
with sequences (which include lists). Learn how to use mapcar, find,
find-if, remove, remove-if, position, replace, reduce, assoc, acons.
- Do not put print statements in your functions. For the most
part your input is entered as function arguments and your output is
just the result of a function you execute. The only exception is if
you need to pretty print the complex data structures which are not
printed nicely by the default LISP printer. If this is the case, you
should write one function that produces the result, and another that
can interpret and print it nicely. When asked to get some timing
results for functions you write, never time the functions that do any
output - it is extremely slow in LISP and the overhead will
completely cover the computation time.
- Make your input format easy for the user. If the assignment
allows you to choose the input data format, it
must be something easy for the user type in or input from a text
file, that is symbols or lists, and never any complex types such as
structures or hash tables. If a more complex data structure is best for internal
implementation, you should provide a conversion function between the
external and internal format.