AssignmentCheckList

CSci 2110 : Assignments/Exercises 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
    Your submission should be a zip file with the following directory structure:

    B00012345_assignment(or lab exercise)Number/ - top level folder named with your student number and assignment number.
       README.txt - Assignment readme file. Please explain how to compile your code, what are needed to compile, and how to run. 
       Q1/ - Folder for question 1 
          Doc/ - Folder with javadoc generated documentation 
          Q1/ Folder with .java files 
       Q2/ - Folder for question 1 
          Doc/ - Folder with javadoc generated documentation 
          Q2/ Folder with .java files

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

 


Code Craft

  1. 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.
  2. Meaningful Names for variable and methods
    • For the most part your variable names should demonstrative of what their function (purpose) is.
  3. 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.
  4. No Magic Numbers
    • Do not use literal values in your code. Use constants.
  5. Avoid Global Variables
    • Global variables should be used sparingly.
  6. Main
    • Most of your code should reside in methods i.e. you should not “compute” anything in main.
  7. 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.
  8. 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.
  9. Data Validation
    • Data read in from an unknown source should be validated to ensure that it is correct. Try your code on different unexpected inputs. 
  10. White Space
    • There should be an effective use of vertical and horizontal white space.
  11. 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.
  12. 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.
  13. Comments
      • Please see the section on comments below.

     


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. See the document “How to Write Doc Comments for the Javadoc Tool” (http://java.sun.com/j2se/javadoc/writingdoccomments/index.htmlfor a good discussion of documentation issues particularly those related to specifying API.

You are to use javadoc comments to document all classes, instance or class fields, and methods (even those that are private). Note that the first sentence of any javadoc comment should be a summary sentence, containing a concise but complete description of the API item. Javadoc supports the following tags:

  • @param (classes, interfaces, methods and constructors only)
  • @return (methods only)
  • @exception (@throws is a synonym added in Javadoc 1.2)
  • @author (classes and interfaces only, required)
  • @see

You are to use standard java comments do document variable and code blocks.

What should comments do?

  1. Comments should convey information in a clear, precise and terse manner.
  2. Comments should convey information about the code that is not obvious from the code itself.
  3. Explain why more than how. (express intent)

“Where to comment” and “What to comment”

    • At the beginning of each  class a javadoc comment including:
      • A summary sentence, containing a concise but complete description of the API item
      • A description of the class and how it does what it is suppose to do Author tag
  • At the beginning of each   method or interface  a javadoc comment including:
    • A summary sentence, containing a concise but complete description of the API item
    • A description of the method and how perhaps a description of the implementation
    • @param (for each parameter)
    • @return (methods only)
    • @exception (as required)
  • 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.

 


Printing Code

  • Fixed sized font is a must!
    It is standard practice to print code in a fixed format because it is easier to read.
  • Lines should be wrapped after ~75 characters
    Lines that wrap make it very difficult for the markers (or anyone else) who has to read your code. Wrap all line that do so.
  • The code should be pleasing to the eye.
    There should be an effective use of vertical and horizontal white space.

 


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
  • Unless specified explicitly, please test your code on 5 different inputs and provide the corresponding outputs.