Professional C__ - Marc Gregoire [63]
int element = inArray[i];
int j = i - 1;
while (j >= 0 && inArray[j] > element) {
inArray[j+1] = inArray[j];
j--;
}
inArray[j+1] = element;
}
}
A better approach would be to include comments that describe the algorithm that is being used. In the modified function that follows, a thorough comment at the top explains the algorithm at a high level, and inline comments explain specific lines that may be confusing.
/*
* Implements the "insertion sort" algorithm. The algorithm separates the
* array into two parts--the sorted part and the unsorted part. Each
* element, starting at position 1, is examined. Everything earlier in the
* array is in the sorted part, so the algorithm shifts each element over
* until the correct position is found for the current element. When the
* algorithm finishes with the last element, the entire array is sorted.
*/
void sort(int inArray[], int inSize)
{
// Start at position 1 and examine each element.
for (int i = 1; i < inSize; i++) {
int element = inArray[i];
// j marks the position in the sorted part of the array.
int j = i - 1;
// As long as the current slot in the sorted array is higher than
// the element, shift the slot over and move backwards.
while (j >= 0 && inArray[j] > element) {
inArray[j+1] = inArray[j];
j--;
}
// At this point the current position in the sorted array
// is *not* greater than the element, so this is its new position.
inArray[j+1] = element;
}
}
The new code is certainly more verbose, but a reader unfamiliar with sorting algorithms would be much more likely to understand it with the comments included. In some organizations, inline comments are frowned upon. In such cases, writing clean code and having good comments at the top of the function becomes vital.
Commenting to Convey Metainformation
Another reason to use comments is to provide information at a higher level than the code itself. This metainformation provides details about the creation of the code without addressing the specifics of its behavior. For example, your organization may want to keep track of the original author of each method. You can also use metainformation to cite external documents or refer to other code.
The following example shows several instances of metainformation, including the author of the file, the date it was created, and the specific feature it addresses. It also includes inline comments expressing metadata, such as the bug number that corresponds to a line of code and a reminder to revisit a possible problem in the code later.
/*
* Author: marcg
* Date: 110412
* Feature: PRD version 3, Feature 5.10
*/
int saveRecord(Record& rec)
{
if (!bDatabaseOpen) {
throw DatabaseNotOpenedException();
}
int id = getDB()->saveRecord(rec);
if (id == -1) return -1; // Added to address bug #142 - jsmith 110428
rec.setId(id);
// TODO: What if setId() throws an exception? - akshayr 110501
return id
}
A change-log could also be included at the beginning of each file. The following shows a possible example of such a change-log.
/*
* Date | Change
*----------+--------------------------------------------------
* 110413 | REQ #005: * | value if values > 32767. * 110417 | REQ #006: */ However, this might not be necessary when you use a source code control solution, discussed in Chapter 23. Every source code control solution, for example CVS, supports check-in comments. You should check-in each change request separately. For example, if you need to implement two change requests in one file, you should check-out the file, implement the first change request and check-in the file with the appropriate change-log comment. Only then you can check-out the file again and work on the second change request. If you want to work on both change requests at the same time, you can branch the source file and start working on the first change request in one branch and work on the second change request in the second branch. When implementation is finished, you can merge