How to properly comment your computer code
1. Every program or library/header file should have a block comment at the top of
the source code that describes the files contents and purpose as well as the
name of the author.
2. Every function should have a block comment describing the following items
a. What the function does.
b. What parameters are taken/supplied?
c. What values are returned?
3. “Inline comments are important around complicated parts of your code, but it
is important to not go nuts here; over-commenting your code can be as bad as
under-commenting it. Avoid commenting the obvious. Your choice of good
function and variable names should make much of your code readable.”
https://www.cs.swarthmore.edu/~newhall/unixhelp/c_codestyle.html
I.
Example of properly commented program description.
You should include a block comment in the following format atop of your program and
line comments as needed throughout your program. This should precede all other code
in the source file.
/*
* Program Name: COP 2220 Project 2
*
* Description: PROJECT-DESCRIPTION
*
* Author: YOUR-NAME (N Number)
*
* Date: WHEN-LAST-MODIFIED
*/
Each function (other than main) must start with a comment block formatted as follows:
/*
* Function Name: FUNCTION-NAME
*
* Input Parameters: WHAT-FUNCTION-TAKES
*
* Description: WHAT-FUNCTION-DOES
*
* Return Value: WHAT-FUNCTION-RETURNS
*/
Larry Snedden
University of North Florida
School of Computing
II.
Example of a properly commented function.
/*
* Function Name: SQUARE_THE_BIGGEST
*
* Input Parameters:
*
n1: Float Type Number
*
n2: Float Type Number
*
* Description: Returns the square of the largest of
*
It’s two input values.
*
* Return Value: Double Type Number
*/
double square_the_biggest(float n1, float n2)
{
//Function definition code would be here
}
These are the expectations of the commenting required for all of your project work.
On exams you will not be expected to comment your work for a grade for the sake of
time but you are welcome to comment your code as you feel the need to help solve
the various problems.
Larry Snedden
University of North Florida
School of Computing