CSCI 152: Operating Systems Programming
Documentation Requirements for Projects
Documentation of Code is required for all projects in the form of comments.
Lack of documentation or bad documentation will result in up to a 20% penalty.
NOTE: If you do your project in Java you must use javadoc tags and turnin the generated javadoc html.
*******YOU SHOULD READ THE SOFTWARE ENGINEERING GUIDELINES INCLUDED WITH YOUR SYLLABUS!*******
Examples of Required Documentation
- Headers at the top of every file (very important)
/********************************************************************
* name of file
* programmer name(s)
* some kind of date (last modified, date created)
* CSCI 152 - Section #
*
* Description:
* Here is a description of this file or class which should be a couple to a few lines long
* and explains what this class does in plain words as if you were explaining how
* this part of the program worked to a friend. Pseudo code can also be included here.
********************************************************************/
- Function Headers (very important)
/********************************************************************
* name of function
*
* description:
* Here is a description of this function or method which should be between a couple
* lines long and explains what this class does in plain words as if you were
* explaining how this part of the program worked to a friend.
*
* Parameters:
* name - name of student
* Returns:
* letter grade student recieved in course
********************************************************************/
- Variable descriptions (very important)
int total = 0; // stores the result when calculating the total number of widgets
String name; // holds the name of the server to connect to
Some psuedo-code would be helpful, either mixed in with functional code or included in function headers.
You do not have to write psuedo-code for the whole program but you should write psuedo-code for critical parts.
- Variable and Function names must be descriptive (very important)
smf( x, d ); //bad names, may loose points
connectToServer( server_name, port_number ); //good names
- If you do your project in Java be sure to turn in javadoc (important)
- You don't have to print out all of the html, just show me that you generated it when you demonstrate your project.
- If you are using C or C++ do not worry about this.
Examples of Dumb and/or Unneeded Documentation
- Stating the obvious is not needed, do not add comments like the following unless they actually help you understand better.
for( int i = 0; i < 10 ; i++ ) // loop ten times
{
print "hello"; // print hello
}
value = 7.8; // assigning 7.8 to value
- Documenting short lived variables is not needed
int i; // the variable i is used in the following for loop (this is very obvious, it does not need to be stated)
for( i = 0 ; i < 10 ; i++ )
{
}
- Documenting every single line is not needed
- If this helps you by all means do it.
- Otherwise don't bother.
- Descriptive names are not needed in cases like the following example
// in this case "i" is much better than "for_loop_counter"
for( int i = 0; i < 10 ; i++ )
{
}
for( int for_loop_counter = 0; for_loop_counter < 10 ; for_loop_counter++ )
{
}
More Help with Documentation
- Since you are going to start on documentation before you start
programming you have plenty of time to show your TA an example to see
if it is acceptable before the project is due.
- Please ask for clarification on any of these items if necessary.