This document provides a convention for indenting and commenting your C and C++ programs that will help you keep track of what you are trying to do, and also be thorough enough so that your graders and lab TA's can help you with problems in your code. Proper indentation allows you to step through the code more easily. The presence of comments helps explain your code quickly to the TA so he/she can help you faster and better. Graders will take points off for programs that do not follow this coding convention.
All programs must include the following header information:
/*******************************/ /* /* Project Name: ... /* Description: ... /* File names: if multiple .c files exist ... /* Date: Project due date /* Lab Section: Your lab section (0101, or 0201, or ...) /* Programmer: Your last name, first name /* email: your email address /* /*******************************/
Please write your comments in complete sentences, or at least in complete thoughts. Avoid ambiguously short comments (one or two-word comments), and avoid commenting the obvious. (eg. a printf call is obvious, but an arithmetic or string operation may not be.) Please note: you are not asked to be obsessively thorough, with paragraphs of comments. However, include a brief sentence or two in strategic places that will make it easier for people to understand your code.
Examples:
1. int age; //stores a person's age
2. // QTEnergy - thermal energy transfer crossing unit area per unit time
float QTEnergy;
3. FILE* inputFile; //file handle for reading data from the input file
Examples:
1.
// These statements decide what description of a person to print,
// based on his/her age (stored in 'age' variable).
if (age < 13)
{
printf ("young kid");
}
else if (age >= 13 || age <= 19)
{
printf ("teenager");
}
else
{
printf ("adult");
}
2.
// Here I decide what arithmetic operation to perform based on
// the operator (variable 'operator') entered by the user.
switch (operator)
{
case '+':
printf ("plus");
break;
case '-':
printf ("minus");
break;
case '/':
printf ("divided by");
break;
case '*':
printf ("times");
break;
default: break;
}
Example
int i = 0;
int iSum = 0;
int iArraySize = 100;
//This loop sums up all the positive integers in an array of integers.
for (i = 0; i < iArraySize; i++)
{
//This is the condition that skips negative numbers.
if (array[i] < 0)
{
continue;
}
iSum += array[i];
}
Note that using strategically placed blank lines to separate sections of code makes it easier to read the code.
Examples
/*
Description: This method sums up all the positive integers in an
array of integers.
Parameters:
array-- the array of integers that are to be summed up.
iArraySize -- the size of the array
Returns:
the sum of the positive integers in the array.
*/
int positiveSum (int[] array, int iArraySize)
{
int i = 0;
int iSum = 0;
//This loop sums up all the positive integers in an array of integers.
for (i = 0; i < iArraySize; i++)
{
//This is the condition that skips negative numbers.
if (array[i] < 0)
{
continue;
}
iSum += array[i];
}
return iSum;
}
Here is a method that returns more than one value (e.g. one which has pointer arguments.) Such a method may affect the memory locations sent via the pointers, and may also return an explicit value. One common method that does this is strcpy. It copies the source string to the target string, and returns the number of characters copied. One possible implementation of strcpy can be as follows:
/*
Description: This method copies the contents of string sSource
to string sTarget.
Parameters:
sTarget-- the string to be copied into, make a copy of the sSource
sSource -- the string to be copied to the sTarget
Returns:
the number of characters copied (Explicit return)
a copy of the target string (implicit via the 'sTarget' variable)
*/
int strcpy (char* sTarget, char* sSource)
{
int iCharsCopied = 0; //counter of characters copied from sSource to sTarget
int i = 0; //loop counter through the sSource string
for (i = 0; sSource[i] != '\0'; i++)
{
sTarget[i] = sSource[i];
iCharsCopied++;
}
return iCharsCopied;
}
Examples:
1.
// This struct describes a car, which has a make (a company),
// a model, and the year.
struct car
{
char* make; //the car's make, or brand
char* model; //the car's model
int year; //the car's year
};
2.
// This struct describes a student, has a name, middle initial
// (if any), a last name, an address at college, and address at home,
// a set of lab grades, test scores, and homework grades.
struct student
{
char* name;
char middleInitial;
char* lastName;
struct address collegeAddress;
struct address homeAddress;
int[] labGrades;
int[] testScores;
int[] homeworkGrades;
};
Please note that good variable names reduce the need for documentation, or even make it redundant (see the car example). In some of the examples we used the convention of prepending the data type of the variable to the actual variable name. For example, a character string variable firstname may be sFirstName, or a variable sum may be iSum if it is an integer sum, or fSum if it is a floating point number. The advantage of this scheme is that you know what the data type is for each variable without tracing back to its declaration. This is useful when you do a large team project and have to work with variables declared by other programmers.