CSCD 211
Programming Principles II
Program Format Requirements


(Documentation typically 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.


  • Main / driver file (file that contains class with main method) - (placed directly above the class declaration):
[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 

         All Methods (except the main method) will contain the following comments placed right above the method declaration

/**
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-known 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 .
  • If the code is obtained from the internet site the complete link, the author (if none, state so) and give a description of what was borrowed.
  • If the code came from another person (via help), state the person’s name and what they do (i.e. tutor, fellow classmate, etc.), and how they helped you.
  • If the code was given in class, cite the day it was given in class, and a description of what was borrowed.
  • If the code was obtained from a book, include the book title, author, publisher, and pages where the code is found as well as a exact description of what is being used.
  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:
    • Class names will begin with a capital letter. Multi-word class names should be separated with capital letters.  
    • Method names will begin with a lower case letter. Multi-word method names should be separated with capital letters.  
    • Constants will be completely capitalized – use an underscore to separate multi-word constants
    • All variables will begin with a lowercase letter.  Multi-word variable names should be separated with capital letters.

Examples:

public class MyClass
{
  public final static int MAX_NUMBER_OF_ITEMS = 100;
  private double totalIncome;	// total income - private instance data
  public void myMethod()
{
String temp, anotherTemp; // local instance within a method - notice there is no m

} // end of method
} // end MyClass

o        Indentation should be used to enhance code readability.  If code belongs to a larger construct, indent it to make that clear. Most syntax highlighting editors will take care of this for you, but use your own discretion.  


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 should be named with YOUR last name, followed by the first letter of YOUR first name, followed by hw#.  Example: capaulthw2.jar – unless otherwise specified
     
  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. Miss class at your own risk!

Last Updated: 2009-09-22 11:05:16