CSci4125 : Assignment Checklist

General

Have you answered the question?
Does your solution take in the required input, produce the require output and meet all the stipulations set out in the question.
Your assignment solutions should not be exercises for the marker to try and guess what you mean. It is your responsibility as the student to demonstrate to the marker your understanding of the material.

Code Craft and Testing are important!
Programming is a professional discipline much like accounting or engineering. Accountants learn to add everything up twice and to double underline the final total. Programmers must learn to write robust, well tested, well documented, maintainable code. A typical marking scheme in this course breaks down as follows: 50% Working, complete program. 20% Code craft (see below). 20% Testing (see below). 10% For excellence, going beyond what the assignment called for in some significant way.

Packaging

Submission
You are expected to submit an electronic copy of your assignment. If you have any problems with the electronic submission process you MUST send an email with an attached copy of your code to the TA BEFORE the assignment deadline.

Format
See here for an example for an example of the required submission format or here for the corresponding zip file. Your submission should be a zip file with the following directory structure:

B00012345/ - top level folder named with your student number 
   README.txt - Assignment readme file. See example for format. 
   Q1/ - Folder for question 1 
      Q1.pdf - Text and graphs summarizing experimental results
      docs/ - Folder with documentation 
      bin/ Folder with code files 
   Q2/ - Folder for question 1       Doc/ - Folder with documentation 
      Q2.pdf - Text and graphs summarizing experimental results
      docs/ - Folder with documentation
      bin/ Folder with code files

Note that if you are using an IDE, for example Eclipse or Visual Studio, your submission may also include supporting files like CLASSPATH and PROJECT.

Code Craft

Indentation
- Do it and be consistent.
- Three or four space is great.
- Tabbing is not recommended unless you change the tab stop to be three or four spaces, instead of the default eight.

Meaningful Names for variable and methods
- For the most part your variable names should demonstrative of what their function (purpose) is.

Loop Counters
- There are few good exceptions to the rule above but, there is one. It is not standard practice to use meaningful variable names for loop counters. In general, a single letter is used e.g. i, j, k etc. but demonstrative names are sometimes used. What you use depends on what you are doing.
No Magic Numbers
- Do not use literal values in your code. Use constants.
Avoid Global Variables
- Global variables should be used sparingly.
Main
- Most of your code should reside in methods i.e. you should not "compute" anything in main.
Modularity
- Methods should not try to do too many different things. In most cases methods of more than 2/3 of a page intricate poorly structured code.
Code Reuse
- Code should be structured to maximize reuse. If the same code is copied multiple places it usually intricate poorly structured code. No one writes beautiful code the first time. You should expect to have to refactor your code, perhaps several times.

Data Validation
- Data read in from an unknown source should be validated to ensure that it is correct.
White Space
- There should be an effective use of vertical and horizontal white space.
Lines should be wrapped after ~75 characters
- Lines should not be so long that they are likely to be wrapped by a printer or editor. Arbitrary wrapping makes code very difficult to read. A common practice is also to wrap before the operator, which emphasizes the association to the previous line.
Modularity
- Think carefully about the modularity of your code. Individual methods should be short and typically do one well defined task. Very few methods should be more than 1/2 a page in length. The longer the method the more carefully it must be documented.

Comments
- Please see the section on comments

Documentation

The documentation that you are to write for assignments in this course should serve both as an API specifications and as programming guide. API specification describes the public interface to classes while programming guide documentation focuses on providing conceptual overviews and descriptions of implementation.

Inline documentation of variables, code blocks and lines. These should be very brief. Good code should be self documenting but this does not mean comments are not needed. It just means that they should be used carefully to aid the readers understanding i.e. Do not comment every line.

Testing

Construct well documented testing classes
List clearly what a test is intended to evaluate
Make sure all methods are covered by the testing
Test boundary conditions
Test exception handlers