Assignment Guidelines ~~~~~~~~~~~~~~~~~~~~~ Course: Computer Science 402b Term: Spring 2006 Instructor: Hanan Lutfiyya E-Mail: hanan@csd.uwo.ca 1 General Guidelines ------------------ Some things to keep in mind: --Each assignment will be executed and verified by the TAs. --Just because a program executes doesn't mean you will get full marks. It must satisfy the specifications stated in the assignment and must be well-design and documented. 2 General Documentation Structure ------------------------------- Your documentation should contain the following elements. o Title page. This should contain at least the assignment number (and name, if one is given), your names, student numbers, and date of submission. o Table of contents. What your document contains and where (you will have to number your pages for this). o You should describe the structure of your program. This includes: oPort(s) being used. oThe purpose of each thread (assuming you are using threads) and when that thread is started or terminated. oFor each process describe the major components. This is intended to be short. The purpose is to give us enough information to make it easier for us to understand your program. o A list of known bugs, if any, should also be provided. If there are no known bugs with your program, PLEASE state that this is the case! o Experience and conclusions. In this section of your documentation, you should discuss what you have learned or discovered with this assignment. 3 Stylistic Guidelines ------------------- When writing documentation for your assignments, here are a few things you should keep in mind. o In addition to documentation content requirements, there are also stylistic requirements. Most important of these is spelling and grammar. It is a university policy that assignments involving a written component (like documentation) must take English proficiency into account during grading. Consequently, some marks will be deducted for spelling and grammatical errors. There are a few things you can do to protect yourself from this: - Read and re-read your documentation before turning it in! You would be surprised how many little things you can uncover by doing this. - Use a spelling checker on your documentation before turning it in. Most word processors include one. Unix systems usually include several, such as ispell. The ispell spelling checker can even be invoked within text editors (in emacs by typing Esc-x ispell-buffer). o As another stylistic point, it is important to be concise and to the point in your documentation. It is equally important, however, not to be too brief. 4 Code Comment Guidelines ----------------------- When writing code for your programs, you should follow these guidelines for commenting the code: Since other people besides you will be reading your code (your partners, teaching assistants, and so on), it is important that your code is well documented internally through good comments. Here are some guidelines you should follow: - Each code file should have a comment block at the top of the file that includes the course number, assignment name and number, instructor's name, your names, your student numbers, the due date of the assignment, the name of the code file, and a brief description of the code contained in the file. (Other useful, but optional, information includes a modification history, and so on.) The following template should be used at the start of the file. /***********************************************************************/ /* Course: Computer Science 402a */ /* Assignment: Assignment n - Sample code file comment template. */ /* Instructor: Hanan L. Lutfiyya */ /* Submitted by: Your names here. */ /* Student Number: Your student numbers here. */ /* Due Date: The due date here. */ /***********************************************************************/ /* code.c - A description of the code within code.c. */ /***********************************************************************/ - Makefiles should have similar comments at the top of the file. The following template should be used at the start of the file. Again, all you have to do is fill it in! # Makefile for: # ============= # # Course: Computer Science 402a # Assignment: Assignment n - Sample Makefile comment template. # Professor: Hanan L. Lutfiyya # Submitted by: Your names here. # Student Number: Your student numbers here. # Due Date: The due date here. # - Functions should have comments before the function that describe it. These comments should include the name of the function, input and output parameters, a list of the functions that call this function, a list of the functions called by this function, and a brief description of what the function does. (If one of these fields does not apply, you should say so, rather than simply omit the field.) The following template should be used for each function. Again, all you have to do is fill it in! /************************************************************************/ /* Function Name: function1() */ /* */ /* Input Parameters: Name and type of parameter 1. */ /* ... */ /* Name and type of parameter n. */ /* */ /* Output Parameters: Return type of function. */ /* Name and type of parameter 1. */ /* ... */ /* Name and type of parameter n. */ /* */ /* Called By: function2() in code1.c */ /* */ /* Calls Functions: function3() in code2.c */ /* */ /* Description: A brief description of function1(). */ /* */ /************************************************************************/ - Finally, comments should be included within functions before major pieces of code describing what the code does. Brief comments should be provided when defining new types and key data structures within the program. (Do not comment every little data structure, as this detracts from the readability of the program, rather than improving it.) Once again, use common sense. If you think something would be difficult for someone else to understand, comment it. o Constants guidelines. Making good use of constants serves a variety of purposes. Selecting and using good constant names helps attach more meaning to your code, and makes it more readable. Using constants wisely also makes modifying your code easier, since values need only be changed in one location. Here are some guidelines you should follow. - You should use constants instead of literals wherever possible, for numbers, strings, and error conditions. In the case of error conditions, either using a True or False condition, or an OK or NOTOK condition is much more useful than just 0, 1, or -1 in your programs. This can be done by defining new types for them, as in: /* Define a boolean type. */ typedef enum boolean_t { False, True } boolean_t; /* Define a status type for simple error conditions in functions. */ typedef enum status_t { NOTOK = -1, OK = 0 } status_t; Variables of type status_t and boolean_t can then be used, as well as the constants False, True, NOTOK, and OK. - If you have a set of common constants, they should be put in a header file (for example, constants.h) and included in multiple C code files where necessary. o Readability guidelines. As was mentioned earlier, your programs must be readable so that both your partners and teaching assistants can easily determine what your code is doing. Through the use of good comments, and constants, this is greatly facilitated. There are a few other things that should be done, however. - Meaningful variable names should be used. Using variables such as f, foo, and so on, make your program more difficult to read. (Canonical variable names, such as i, j, and k, for loop counters are acceptable, but not recommended.) On the other hand, variable names that are too long are cumbersome, and difficult to use. Again, use your own best judgment. - Space your program appropriately. It can be surprising how indenting your program and inserting lines between main pieces of code and functions can enhance the readability of a program. It is also important that you be consistent in how this is done. Pick one style of spacing, and stick to it. - DO NOT USE A GOTO STATEMENT IN YOUR CODE!!! Doing so is a very poor programming practice, and it can usually be avoided, except in complex exception handling. Using it will result in a very poor style mark (see below). The only reason why this is being mentioned here is that last year, one student used a goto statement in assignments, not once, but twice (even after being harshly penalized the first time). o For those of you who want something to help clean up your coding style, in terms of spacing, you may want to look at Unix programs such as cb or indent. These programs can reformat your C programs in a variety of ways. Using these programs, however, is no guarantee of good-looking code. Use our own judgment.