Guidelines for Homework Submissions

Network Programming, Spring '96

Contents:

• How to submit an assignment
• What to submit
• When to submit
• Grading criteria
• The Writeup

A short example:

collinsr@fork:tmp$ ls
./      ../     dir_1/  dir_2/  file.1  file.2
collinsr@fork:tmp$ tar -cf submit.tar *
collinsr@fork:tmp$ uuencode submit.tar submit.tar.uu

... and then the submit.tar.uu file can be mailed to netprog-submit. (Note that tar also includes any subdirectories you may have.) Only mail the submission file- any comments you send in addition to the uuencoded file won't be seen by human eyes. Either mail such comments to netprog or include them in a file with the rest of your submission.

The receipt will be mailed to the address from which the submission was mailed, and this address will be also be the one to which the grade report will be sent. (This has caused confusion in the past when a student submitted from an off-campus account and became alarmed when their grade sheet never showed up in their RCS mailbox.) If the project is a group effort, and the group members wish to be mailed individual copies of the grade sheets, please include a note in the writeup.

Multiple submissions are allowed; unless otherwise notified, I'll grade the most recent submission.

• a makefile, whose default target makes all the project executables
• a short writeup (discussed below)
• the source code to the project (seemingly obvious, but you'd be surprised...)
• any other support files your project needs (sample data files, etc.)

Remember, for group projects, include a listing of who did what.

The late penalty is ten points a day.

Remember, if you want an extension, talk to Dave WELL BEFORE the due date!

• the implementation: The executable program, generated by the source code and makefile, which actually solves the problem posed in the assignment.
• the documentation: The writeup, which discusses the techniques and tradeoffs and design decisions made in crafting the implementation.
• the source code: The interface between the solution described in the document and the implementation.

• 50% IMPLEMENTATION:
  • does it work? Does it do what the assignment says it should?
  • is the program moderately tolerant of unexpected situations presented by the user? (i.e. if I run it without arguments, does it coredump or does it print out a usage message?) Your programs 't have to be uncrashable (except when otherwise noted... :) but they should perform simple checks on and avoid crashing due to basic user errors.
• 25% DOCUMENTATION:
  • (described below)
• 25% SOURCE CODE:
  • Is the source code an elegant and efficient implementation of the concepts described in the documentation?
  • Is the code tolerant of unexpected situations presented by the system? e.g. are the return codes of all the system routines checked?
  • Is the code easy to follow? Or is it full of mysterious numeric constants and strange coding tricks?

Note that some of this is purely subjective, especially "elegance" and the "is the code easy to follow" phrases in the source code criteria. In general, write the documentation assuming that the user (i.e. the grader) has read the assignment, and comment your code assuming that the user has read the documentation. There is no hard-and-fast rule on quantity of comments or anything like that; it's entirely possible to hand in source code that has no comments (except your name) and is very easy to follow, or to hand in code that is full of comments and is totally uncomprehensible.

To make the project, type make; to run it, say a.out hostname.

Another submission (for the same project) was received whose documentation was a five page Microsoft Word document containing a line-by-line description of the program ("Line 520: a socket is created using the socket() system call. Line 521: ...") Between these two lurks what you should aim for in your writeup.

The writeup should be a brief description (no more than a page or so is necessary) of what your project is and how it works, without getting bogged down in the source code. The source code implements a solution to a problem; describe the solution and its relationship to the code, rather than the nitty-gritty details of what the code is doing. (Leave that for the comments.)

DO INCLUDE:

• your name(s).
• your email address(es).
• which platform (SunOS? AIX? Irix? Linux?) your program runs on.
• how to run your program.
• A medium-to-high level discussion of what's going on ("The connection is opened in non-blocking mode in net_util.c... " "A linked list of name servers is created; connectToServer() tries each of these in turn..." "The flow of control in the program is determined by a switch statement in userInterface.c...")
• Descriptions of any particular concepts embedded in your program(s) (i.e. is there a protocol between your client and server?)
• Any oddities or special notes about your project.

• long, run-on sentences describing what your code does line-for-line (or even function-for-function.)
• html or mime-encoded Adobe Acrobat files. Please use normal ASCII text with 80-column margins.

Back to the netprog home page