Guidelines for Homework Submissions Network Programming, Spring '96 This document describes the submission process and grading criteria for homeworks in Network Programming. --------------------------- HOW TO SUBMIT AN ASSIGNMENT: --------------------------- All assignments will be submitted via email; you should mail a uuencoded tar file to netprog-submit@cs.rpi.edu. Upon receipt, your submission will be decoded and un-tarred, and the output of this process will be mailed back to you so that you can be sure (a) your project was received and (b) I received what you meant to send. 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. --------------------------- WHAT TO SUBMIT: --------------------------- All submissions must include: - 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.) Do *NOT* include compiled executables or object files. Remember, for group projects, include a listing of who did what. --------------------------- WHEN TO SUBMIT: --------------------------- Projects are due by midnight of the due date. A project is considered "received" when the submission-handling program successfully unpacks your submission. The late penalty is ten points a day. Remember, if you want an extension, talk to Dave WELL BEFORE the due date! --------------------------- GRADING CRITERIA: --------------------------- The homeworks will be graded according to the view that they are not just programs, but *solutions* to the problem posed in the assignment. A homework submission can be considered to have three parts: - 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. Here are the weights and criteria for each of the three: 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. --------------------------- THE WRITEUP --------------------------- Last semester, a project was received whose entire documentation consisted of the following: 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. DON'T INCLUDE: - 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.