CSCD 300
Data Structures
Program Format Requirements


(Documentation counts for 20% of your total score for each program. Program design and correctness counts for the other 80% )

I. GENERAL STRUCTURE OF PROGRAM:


Your java files

Comments within your source code:

All files will use the javadoc documentation standard.  The standard is as follows: 

    Example:

    /** 
     * This is the description part of a doc comment
     *
     * @tag    Comment for the tag
     */

Break any doc-comment lines exceeding 80 characters in length with <br>  If you have more than one paragraph in the doc comment, separate the paragraphs with a <p> paragraph tag.


[declaration part: here you import other classes]
/**
* This is a detailed description of the class.
*
* <p><b>
* Extra Credit:
* </b><pre>
* Whether or not you attempted the extra credit (if applicable)
* NOTE: It is not sufficient to merely say the extra credit was implemented,
* describe what the extra credit was.  If you do not mention that you did
* extra credit in this description, the grader will not give credit for it.
* </pre><b>
*
* History:
* </b><pre>
* List of changes, updates, fixes revisions which includes date
* </pre>
*
* @author Your Name
* @see "Any class whose documentation aids in understanding the
* implementation of your class"
*
* Proper citation of code borrowed from anther source
* - for web sites put the URL, the authors name,
* and description of what was borrowed
* - for a book, paper, etc put the Title, the author,
* publisher, pages, and description of what
* was borrowed
*
* NOTE: - Each citation must be contained within quotation marks
* - Break up each @see with <br> after the ending "
* - If you did not borrow code then your @see should simply be
* @see "No Borrowed Code"
*/
[declaration part: here declare your class] - NOTE: the declaration of the class
must come immediately after the comments.
Now include the main method (and any other methods that the class may contain)

The template for main can be found here: main.txt
 
[declaration part: here you import other classes]
/**
* This should be a detailed description of the class.
*
* @author Your Name
* @see "Any class whose documentation aids in understanding the
* implementation of your class"
*
* Proper citation of code borrowed from anther source
* - for web sites put the URL, the authors name,
* and description of what was borrowed
* - for a book, paper, etc put the Title, the author,
* publisher, pages, and description of what
* was borrowed
*
* NOTE: - Each citation must be contained within quotation marks
* - Break up each @see with <br> after the ending "
* - If you did not borrow code then your @see should simply be
* @see "No Borrowed Code"
*/
[declaration part: here declare your class] - NOTE: the declaration of the class
must come immediately after these comments.
[Constants and variables must be described if name does not make it
obvious as to what they are about]

The template for other classes can be found here: other.txt
 
/**
* This first sentence will appear in the method summary. This method description should be a
* detailed description of what the method does. You should have more than one sentence, just
* know the first sentence appears in the method summary but all the sentences appear in the
* method detail
*
* @param List the name (not the type) and then a description of the data
* - if the method takes more than one parameter you will need additional @param * on the next line * - if the method takes no parameters, do not use a @param tag
* @return List the type and then a description of the data
* - if the method does not return a value: DO NOT USE THE TAG * - if the method is a constructor, DO NOT use the tag at all since * constructors never return a value
* @exception List the exception class name and then a description of what would cause
* an exception to be thrown.
* - if no exception is thrown list none - No exception thrown
* @see "Any class whose documentation aids in understanding the
* implementation of your class"
*
* Proper citation of code borrowed from anther source
* - for web sites put the URL, the authors name,
* and description of what was borrowed
* - for a book, paper, etc put the Title, the author,
* publisher, pages, and description of what
* was borrowed
*
* NOTE: - Each citation must be contained within quotation marks
* - Break up each @see with <br> after the ending "
* - If you did not borrow code then your @see should simply be
* @see "No Borrowed Code"
*/
The template for methods can be found here: method.txt. 

Samples of commented Java Files as well as the javadoc output
can be found here:

II. SPECIFIC DOCUMENTATION RULES

  1. Variables/constants
    You are only required to comment the purpose and use of variables when their usage is not obvious from the program context. This is a gray area, so just use your best judgment. You will never, however, be scored down for including reasonable variable comments. 
  1. Method Descriptions - (See - Your Java Files).
    All methods other than the main method will have a description  The description should be set apart from the code using the javadoc standards outlined above.  If any well-know algorithm is used in the method, this should be mentioned, i.e., Bubble-sort, Picard's method, etc.
     
  2. Whitespace
    You should use blank lines to separate blocks of code from each other to enhance code readability, for instance between the program header and the declaration section, between the declaration section and the body of the program, between methods, or even between code structures such as loops, to distinguish them from the rest of your code.

  3. Citations
    Any code that you use that was not created by you needs to be cited as a professional courtesy.  Properly citing is a MUST .
  1. Capitalization/Indentation
    Java is case sensitive! All Java keywords are lower case. You may use any reasonable names for methods and variables as long as you follow the following requirements:

III. MISCELLANEOUS

  1. Program files
    In order for your program to be graded, you must make available to the grader a compressed file (.jar) ALL .java files necessary for the program to execute.  This means that you MUST submit all source code necessary for proper compilation and subsequent execution. The compressed file MUST be named with YOUR last name, followed by the first letter of YOUR first name, followed by YOUR section, followed by hw#.  Example: capault01hw2.jar 
     
  2. Paths in code
    Do not hard code paths for files in your code.  Paths that are specific to your machine mean that your program will run properly on your machine ONLY.
     
  3. The Fine Print
    Some assignments will have special requirements. These will be explained in class and you will be expected to adhere to them as you would these written rules. In other words, "we reserve the right to change, add to, or delete from this list at any time in the quarter." You will ALWAYS be informed of any changes during class. If you miss a class and do not hear the new requirements, you are still responsible to adhere to them. Missing class is a hazard you take at your own risk!

Last Updated: 2009-11-16 10:34:36