Comments in the header file will follow this pattern:
/*
[First, a general description of the class (so a client programmer can tell
right away whether she wants to use it). Just a couple of sentences is fine.]
[Next, a listing of all of the prototypes of public members, each with pre
and post conditions, like this:]
return-type f1(parameters);
pre: [pre condition here]
post: [post condition here]
return-type f2(parameters);
pre: [pre condition here]
post: [post condition here]
return-type f3(parameters);
pre: [pre condition here]
post: [post condition here]
return-type f4(parameters);
pre: [pre condition here]
post: [post condition here]
etc.
*/
[Next, the actual class declaration, with no comments, like this:]
class someClass {
.
.
.
};
Comments in the implementation file will follow this pattern:
[First, a class invariant and description of the private data members] [Next, all of the function definitions. Comments are only required on private member functions and functions that contain complex code that needs additional explanation.]