Pseudocode

Pseudocode is usually a more effective means of communicating an algorithm than a narrative paragraph. Pseudocode should not be merely a statement-by-statement rephrasing of the code — how would that be any clearer than the code itself? For example, if we had to describe the algorithm for finding the average length of the words in a string as implemented by this code:

	...
	int totLength = 0;
	int nWords = 0;
	for (int pos = 0; ; )
	{
	      // find start of word
	    while (pos != s.size()  &&  ! isalpha(s.at(pos)))
		pos++;

	      // if no word, break
	    if (pos == s.size())
		break;

	    int start = pos;

	      // find end of word
	    do
	    {
		pos++;
	    } while (pos != s.size()  &&  isalpha(s.at(pos)));

	    totLength += pos - start;
	    nWords++;
	}
	if (nWords == 0)
	    cout << "There are no words in the string" << endl;
	else
	    cout << "The average word length is "
	         << static_cast(totLength) / nWords << endl;
	...

a suitable pseudocode rendition would be:

	...
	repeatedly:
	    find start of next word
	    if no remaining words,
		break
	    find end of word
	    add word length to running total
	    increment number of words
	write average length, or that there were no words
	...

whereas the following is too detailed to give a clear understanding of what's going on, and just restates almost every line of code:

	...
	set total length to 0
	set number of words to 0
	repeatedly:
	    while current character is not alphabetic
		go on to next character
	    if no remaining words,
		break
	    save start position of the word
	    while current character is alphabetic
		go on to next character
	    add word length to total length
	    increment number of words
	if there were no words,
	    write the no word message
	else
	    write the average length of the words
	...

Presenting the algorithm as a sequence like the following doesn't make the loop structure of the algorithm visually clear:

1. Start a loop.
2. Find the start of the next word.
3. If there are no remaining words, break out of the loop.
4. Find the end of the word.
5. Add the word length to the running total.
6. Increment the number of words.
7. Loop back to step 2.
8. When the loop is done, write the average length, or that there were no words.

A narrative description like the following is practically useless; it's too detailed and completely hides the structure of the code:

First, set the total length to 0 and the number of words to 0. Then go into a loop. Inside the loop, first start a loop that checks every character until it finds a letter. If there was no letter, break out of the outer loop. Otherwise, save the start position of the word. Then start another loop that checks every character looking for a non-letter marking the end of the word. Add the length of the word to the total length and increment the number of words. When the outer loop is all done, if the number of words is 0, write the no word message, otherwise, write the average length.