SamfordUniversity Computer Science Programming Standards
General
Unless instructed otherwise, you must do your own work. Other than authorized teamwork, this precludes working with another individual on an assignment. In all cases it precludes copying the work of another, using material obtained from the Internet, etc. Violations are considered serious and can jeopardize a student’s standing with the university.
Documentation Standards
Program Header Contents
The following example indicates how to preface program code. Include each component (with the possible exception of the Notes section which is only included if necessary to clarify some aspects of the program), showing information pertinent to your specific application. Update the date each time you modify the code.
//Program:net.java
//Course:COSC210
//Description:General purpose neural network program for multi-modal memory strategy and sequence
//processing research. Supportsinter-module connections via linked lists to facilitate
//processing and storage for large numbers of neurons withsparse connectivity.
//Author:Steve Donaldson
//Revised:8/23/12
//Language:Java
//IDE:NetBeans 7.2
//Notes:This program should provide the capabilities for neural netresearch which will lift its
//author from the pit of obscurityto the pinnacle of anonymity.
//*******************************************************************************
//*******************************************************************************
Class Header Contents
The following example indicates how to preface class definitions. Include each component. If there are no data values or constants, simply indicate “None.” You may also wish to add a date, but this is optional.
//Class:NeuronClass
//Description:Collection of neurons in a specified module
Variable and constant definitions go here…
After each class definition and the accompanying code, add two comment lines of asterisks:
//*******************************************************************************
//*******************************************************************************
Method/Function/Procedure/Subroutine/Subprogram Header Contents
The following example indicates how to preface subprogram code. Include each component. If there are no parameters or return variables, indicate “None” and “Nothing,” respectively You may also wish to add a date, but this is optional.
//Method:getInteger
//Description:Permits keyboard input for integer values. Be sure to include any
//necessary pre-conditions for proper method operation.
//Parameters: prompt[ ]descriptive text for info to be input
// currentIntthe value of the integer prior to user input
// minValuethe minimum allowable value for the integer
// maxValuethe maximum allowable value for the integer
//Returns: current(define the value returned if not defined elsewhere)
//Calls: getUserInput
// displayMessage
//Globals:totalEnergy
Method code goes here…
After each method definition, add a single comment line (not required for interfaces):
//********************************************************************
General Header Note
Alignment and Indentation
Align code by block. Indent each section (method within class, loop within method, selection within loop, etc.) by two or three spaces. Make a concerted effort to align comments, regardless of block indention.
Naming Conventions
1. Use descriptive names for variables (e.g., “actionPotential” in lieu of “ap”).
2. Follow the standard variable naming convention for the language being used. For example, with Java: begin class names and major words within a class name with capital letters and use lowercase letters or digits for the remaining characters (e.g., ClassName); begin standard variable names and method names with lowercase letters and use lowercase or digits throughout, except for the beginning of major words embedded in the variable name, which should begin with a capital letter (e.g., variableName). Use uppercase (perhaps with digits) throughout for constants and make them “final”.
Comments
Comment liberally with the express goal of providing clarity for the reader. Do not add superfluous comments (e.g., a=b+c; //add b to c to give a). To the greatest extent possible, make code self-documenting (e.g., use descriptive variable names). One frequent need for quality comments is for the proper description of variables, particularly when there is a range of valid values and/or when the values must correspond to some specific unit of measure. The following provides an example of a fairly extensive (but necessary) comment to describe a variable.
double connectionDecayRate;//controls connection decay per time step: 0=no decay (i.e., the
//connection is preserved intact); 1=decay is complete after one
//time step (i.e., the connection strength decays immediately);
//.xx=fractional amount such that larger .xx means faster decay
Do not allow the comments on any line to extend beyond the point where the line will wrap when printed in landscape mode. (In general, this will require you to use less than 100 columns.) If necessary, use multiple lines (as in the example above) and align the comments to promote readability.
Submission Requirements
In general, you are required to submit a printed copy of the source code plus a machine readable copy of the source (matching the printed version) and an executable version of the program. For some courses, the instructor may waive one or more of these requirements, modify them slightly, or insert additional ones. Do not submit code that will not compile! It will be returned with a grade of zero. Use good software engineering principles and build your programs incrementally.
Programming standards updated 08/23/12