Commenting Code and Writing Styles
You need to follow the following guidelines about commenting:
- Always have a "Program Header" on each file that lists the name of
the Program/Class contained, the Author, date of creation, updates,
Purpose, and how to call the program (if appropriate). See example
below
- Before each class, put comments that tell the user the pupose of
the class.
- Before each method inside of a class, put comments on what it does
and how to call it.
- Comment inside each method and at variable declarations as appropriate
so that users can understand what the code is doing with ease.
- Don't overcomment or undercomment, use common sense.
- Use indention rules to make your code easy to read.
/*
Program: Run_Car
Author: Lynne L. Grewe
Date: Sept. 22, 1998
Updates:
Sept. 23, L. Grewe, Changed Comments created ....
.......
Sept 28, D. Sullivan, ............
Purpose: A class you can use to represent a generic Car.
Call: N/A
*/
/*The Car class represents a generic Car
contains variables about Engine_Size, Gas_Tank
*/
class Car {
float Engine_Size;
float Gas_Tank;
//Sets Gas_Tank to 100%
void Fill_Tank() {
Gas_Tank = 100.0;
}
//Allows user to specify new Engine Size
void Change_Engine(float size) {
Engine_Size = size;
}
}
|
|