The following applies to Programming I, II, III, Web Programming classes. Non-programming classes will be given class specific guidelines where applicable.
Commenting guidelines are structured to conform to professional guidelines as much as possible to help train the student in professional coding practices. All submitted code must conform to the following guidelines EXACTLY. Failure to do so will result in your submission being penalized, up to and including being rejected and an assigned grade of zero. The following guidelines, and classes in general, are designed to simulate real-world software engineering practice as much as possible.
No variations on these standards will be accepted.
All code files must contain the following comment block header at the top of the file.
In C/C++ this includes both header files and cpp files. In all other languages, if it has code
in it, it needs a comment header (.py, .js., .php, .html, .css, etc.)
#############################
# Name: Jane Doe
# Assignment: 1
# Purpose of the file: 1-2 paragraphs explaining
# the purpose of the code in the file.
#############################
/**************************
Name: Jane Doe
Assignment: 1
Purpose of the file: 1-2 paragraphs explaining
the purpose of the code in the file.
***************************/
<!-- -----------------------
Name: Jane Doe
Assignment: 1
Purpose of the file: 1-2 paragraphs explaining
the purpose of the code in the file.
------------------------ -->
All functions/methods must be commented appropriately to professional standards. The following applies only to Programming I, II, III. Failure to comment functions/methods properly will result in a substantial grade penalty, up to and including a zero.
def divide(x, y):
"""
This function accepts two values, tests
them for type, rejects non-numerics with
an exception, divides numerics x by y,
treating them as floats, and returns the
result. Divide by zero throws an exception.
@param (float) x : dividend
@param (float) y : divisor
@return (float) x/y : quotient
@exception (TypeError) : non-numeric in either x or y
@exception (ZeroDivisionError) : y == 0
@note note anything worthwhile here or leave this line out
"""
if not isinstance(x, int) and not isinstance(x, float):
raise TypeError("first parameter is not a numeric type")
if not isinstance(y, int) and not isinstance(y, float):
raise TypeError("second parameter is not a numeric type")
if y == 0:
raise ZeroDivisionError
return (float(x)/float(y))
double divide(double x, double y){
/*********************************************
This function accepts two values, casts
them to double regardless of numeric type passed,
divides double x by double y, and returns the
double result. Divide by zero throws an exception.
@param x : dividend
@param y : divisor
@return x/y : quotient
@exception (int) : y==0
@note note anything worthwhile here or leave this line out
*********************************************/
if(y == 0){
throw 0;
}
return x/y;
}
main( ) should be commented by the same rules as any function, with command line parameters (if any) detailed just like any parameter. Driver files without a main( ) (e.g. a Python 'script') should be commented by the same rules as any function, with command line parameters (if any) detailed just like any parameter.
class Circle:
"""
This class defines a Circle. It must be passed
a radius which defaults to __MINR if an invalid
a radius which defaults to __MINR if an invalid
value is passed (i.e. negative number).
@attrib (float) __radius : the radius of the circle
@attrib (int) __MINR : the default radius of the circle
"""
def __init__(self, radius):
"""
Constructor. Pass in a posive float
value to set the radius.
@param (float) radius : the radius of the circle
@return na : na
@exception na : na
"""
self.__MINR = 1
self.setRadius(radius)
def getRadius(self):
"""
Returns the private attribute __radius
@param na : na
@return (float) self.__radius : the radius of the circle
@exception na : na
"""
return self.__radius
def getArea(self):
"""
Calculates and returns the area of the circle.
@param na : na
@return (float) : the area of the circle
@exception na : na
"""
return math.pi * (self.__radius ** 2)
def setRadius(self, radius):
"""
Sets the radius of the circle which must be
positive or it will default to __RMIN
@param (float) radius : the radius of the circle
@return na : na
@exception na : na
"""
if radius > 0:
self.__radius = radius
else:
self.__radius = self.__MINR
class Circle {
/*********************************************
This class defines a Cirlce. It has two constructors
and can be instantiated with a default radius or with
a caller assigned radius.
@attrib radius : the radius of the circle
*********************************************/
public:
/**********************
Constructors/Destructor
***********************/
Circle();
Circle(double);
~Circle();
/**********************
Getters/Accessors
***********************/
double getRadius();
double getArea();
/**********************
Setters/Mutators
***********************/
void setRadius(double);
private:
double radius;
};
All code should be commented appropriately to professional standards.