CSE 422S Grading Rubric

Please treat each lab assignment as you would a commercial or research product that you are shipping to a group of customers. Please take the time to test, document, and check your work to make sure all parts are shipped, are of high quality, and behave resonably under a range of different operating conditions. Grading will focus both on the quality of your solution and on the quality of the product itself, as submitted. To ensure the best possible result (and accordingly the highest possible grade), please pay attention to the following issues:

Correct Compilation and Operation

The source and header files you submit must compile correctly using the gcc compiler version specified in Studio 1, and must run correctly on the machines specified in the lab assignment. Please compile with the maximum warning level set (-Wall for this course) and make sure your program compiles without warnings (and of course without errors). Note that warnings are intended to make you aware of potential issues in your code, even if syntactically correct. In almost all cases, these warnings should be heeded and fixed. Missing files will be handled with a 5 point deduction (possibly per file) if you need to supply one or more new files in order for us to build your solution.

Design Quality

Design decisions are largely yours to make, and as long as the design is concise, coherent, consistent, and addresses all requirements of the assignment, you will receive full credit. One key issue to consider is whether each abstraction in your design does a single job, does that job completely, and collaborates appropriately with other abstractions. Minor deductions (1-3 points, but please be aware minor deductions can add up) will be made for abstractions that are unnecessarily large or have inappropriate inter-dependencies. Major deductions (5-15 points) will be made for larger problems like neglecting key requirements of the assignment, code that does not compile or that crashes when it runs, etc.

Implementation Quality

How you implement your solution is again up to you, and we will take into account different approaches to implementation. Minor deductions will be made for things your program gets away with but are not good, like neglecting to check the return value from a system call or other function call (i.e., the program may have problems under special conditions), or calling exit(1) from inside a function rather than providing a clean termination path. Major deductions will be made for problems that produce incorrect or extremely inefficient behavior of the program. The former kinds of errors should be eliminated during your coding and code review phases, and the latter kinds of errors should be eliminated during your testing phase, which should include running different combinations of inputs involving well formed and/or badly formed contents and making sure that your code gracefully handles bad inputs as well as good ones.

Coding Style

Different coding styles will also be accepted, as long as they are clear, readable, and consistent. Please code clearly with both the reader of the code and the user of the program in mind. Please use consistent indentation and placement of braces, and comment your code thoroughly. Use whitespace liberally - it's free and it makes it a lot easier to read your code. Remember, you don't write code in a vacuum. Code must be maintainable, not only by you, but by the other people you work with, or the general open-source community. Clear documentation helps when you return to code you wrote in the past, and may not otherwise remember what you have done. When grading, we may add tagged comments to the code indicating areas where we found particular issues to mention, whether or not points are deducted. Only minor deductions will be made for each style issue, except in extreme cases.

Documentation

Please make sure you provide adequate instructions on how to unpack, build, and run your program. Also, please make sure to document your solution. Minor or even major deductions will be made for inadequate explanation of how your solution does what it does, why you made key design choices, or how the user (or grader) can successfully build and run your program. Even if how you did something is obvious to you, please assume it is not obvious to the reader.

Missing Files

Missing files in the delivered software make it difficult or impossible to evaluate your solution. A deduction of up to 5 points will be applied for each missing or corrupted file that is submitted later on request.

Late Submission

Labs recieved within 24 hours after the deadline will be graded with a 10 point deduction. Labs received more than 24 hours after but within 48 hours of the deadline will be graded with a 20 point deduction. Labs received after 48 hours from the deadline will not be graded, except under extenuating circumstances. If you anticipate running late completing the assignment, please let us know about the trouble as soon as possible (especially as it may be possible to give you an extension if you request it ahead of time, though the penalty for any deadline that has passed when the request is made will be applied). In any case please turn in as much as you can before each deadline so we can give at least some credit for the work you have done.

Grading Issues from Previous Semesters

Please avoid the following practices, which have drawn at least comments (and often deductions depending on the extent of the issue) in previous semesters:

Using hard coded numbers like 2 or 7 (possible exceptions are the constants 0 or 1) instead of using a descriptively named const variable, enumeration label, or manifest constant. For example, a section of code might look like:
```
     char * message = "Hello!\n";
     write(STDOUT_FILENO, message, 7);
```
Here, the use of the hard-coded length is problematic. It introduces the possibility of error (what if you miscounted?) and makes maintainability difficult (what if you need to change the message, or make it dynamic?). Instead, use code like:
```
     char * message = "Hello!\n";
     write(STDOUT_FILENO, message, strlen(message));
```
Using names like ONE or TWO that don't adequately convey their purpose or role in the code; for example, don't use ONE for the argv index for the first command line argument after a user-space program's name, but instead name it something that indicates the purpose of that argument in the program's command line. If the same value is used for multiple purposes, then a having a distinct const variable, enumeration label, or manifest constant for each such purpose (each having that same value) would be appropriate.
Using dynamic memory allocation without appropriately freeing that memory along every path in the code

Using the same error message or error return code for different kinds or causes of failures. One alternative is to enumerate the failure cases, e.g.:

     enum return_vals {
          SUCCESS,
          ERROR_OPEN,
          ERROR_WRITE
     }

     int main(int argc, char * argv[]) {

          ...

          fd = open(filename, O_APPEND);
          if(fd == -1) {
               return -ERROR_OPEN;
          }

          result = write(fd, buf, count);
          if (result == -1) {
               return -ERROR_WRITE;
          }

          return SUCCESS;
     }

Using a pointer/size arithmetic formula without a comment explaining it: in general any non-obvious code should have a comment giving an intuition of what it does in general terms (and even better explaining why or how it does it that way)
Putting function definitions in a header file
Unnecessary format restrictions, e.g., not tolerating blank lines and extra whitespace in a file that is being read as input
Leaving commented-out code fragments in code - please either remove these before submitting them or use conditional compilation via precompiler directives to bring them in/out (and then be sure to comment why doing so is appropriate)
Adding comments for things that are already fairly obvious from the code (e.g., begin and end of a function unless it's reasonably long - at which point it's better style anyway to break it into smaller functions if possible)
Using exit to end the program in the middle of any function that could be called from another function (including main), except when necessary in a termination path cleanup function (and in that case please give exit a manifest constant to return as the program's return value).
Using fixed length buffers when the lengths of inputs to them are variable or unknown
Unnecessarily cramping symbols or lines together, which impacts readability - use whitespace generously: it's free!

Please use the following practices to improve the clarity and quality of your code and documentation:

Organize code that cleans up memory and other resources into one or more common functions that can be called from various branches of a program's logic, either for error conditions or successful completion. Initialize pointers and other variables so that when the function is called it can distinguish resources that do need to be cleaned up from those that don't (for example if a failure occurs mid-way through a series of calls to malloc). Don't forget that in addition to cleaning up memory, networking ports need to be unbound, files and sockets need to be closed, etc.
in header files either use #pragma once or use precompilation include guards as the following code illustrates, to avoid duplicate inclusion:
#if ! defined (MY_FILE_H) #define MY_FILE_H // body of the header file #endif /* MY_FILE_H */
check the return value from any call that could return an error code after a failure (e.g., malloc)
use constant variables with descriptive names and appropriate types, in preference to precompiler #define macros
use consistent and appropriate comments
discuss design decisions in your writeup
test your code for its handling of error cases as well as of the "happy path"
perform "tiger team" testing - trying to find cases that break your program, and then fixing them
using whitespace generously: it's free and it improves readability!