Why you need to be writing pseudo code

From time to time, computer code is unrecognizable after sitting in storage for a long time, or even as short as two weeks. This is particularly applicable to coding of logic, loops, and data formatting.

Here is a simple enough example: randomly sorting elements of an array. This is taken from a module on the C# learn.microsoft.com training. Here is the link:

Exercise — Create a method to shuffle an array — Training | Microsoft Learn

First take a look at the code without any explanation:

using System;

string[] pettingZoo = 
{
    "alpacas", "capybaras", "chickens", "ducks", "emus", "geese", 
    "goats", "iguanas", "kangaroos", "lemurs", "llamas", "macaws", 
    "ostriches", "pigs", "ponies", "rabbits", "sheep", "tortoises",
};

RandomizeAnimals();
// string[,] group = AssignGroup();
Console.WriteLine("School A");
// PrintGroup(group);

void RandomizeAnimals() 
{
    Random random = new Random();

    for (int i = 0; i < pettingZoo.Length; i++) 
    {
        int r = random.Next(i, pettingZoo.Length);

        string temp = pettingZoo[r];
        pettingZoo[r] = pettingZoo[i];
        pettingZoo[i] = temp;
    }
}

It is easy to identify something about an array of animals in a petting zoo, and the innermost three lines of code are an understandable swap:

string temp = pettingZoo[r];
        pettingZoo[r] = pettingZoo[i];
        pettingZoo[i] = temp;

What is needed is an explanation of the iterations of the for loop. Pseudo code can help.

/*
  Randomly shuffle an array.
  
  Loop through an array, swapping two elements
  The first swap is with the starting element in the array and some 
    random remaining element of the array.
  The starting element is now shuffled, and it's original contents are
    now placed somewhere into the remaining elements of the array
  To prevent the starting element's new content from swapping a second time, 
    increment the for loop to step along to the next element in the array.
  Keep in mind that the array is now one element shorter, so
    use array.Length to keep track of the reduced number of array elements.
  The first swap is element [0] and some random element less than the
    length of the array. If the array has 18 elements as in this example, 
    then the first swap is between elements [0] and among [1] through [17].
  The second swap is between element [1] and among elements [2] through [17].
*/

With that example done with, here is a list of considerations when commenting code. These are taken from “The Zen of Python, by Tim Peters” entry #20 in the Python Enhancement Proposals in 2004, optained by typing the following into a python editor.

Import this

after running the one-line script, the document should appear on the console.

The Zen of Python, by Tim Peters

Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Specifically relating to comments, the Python Enhancement Proposal #8 offers some guidlines:

• Write comments that will not contradict the code or mislead the reader. They’re much worse than no comment at all.
• Update your comments when your program gets updated.
• Write comments as complete sentences (capitalize the first word if it’s not an identifier, and end your sentence with a full stop)
• When writing block comments with multi-sentence comments, use two spaces after each full stop ending a sentence, except after the final sentence.
• Write comments in English (unless you are 100% sure that the code will never be read by people who don’t speak your language.)
• Comments should consist of no more than 72 characters per line (but you know that already).

Block comments

Block comments are usually longer, and you should use them to explain sections of code rather than particular lines. They let you leave information for the reader in multiple lines (and multiple sentences). Generally, block comments:

• should refer to the code that follows them;
• should be indented to the same level as the code they describe.

Inline comments

Inline comments are comments that are written on the same line as your statements. They should address or provide further explanation to a single line of code or a single statement. You should not overuse them.

Source: Edube Interactive :: 3.1.1.11 PEP 8 — Comments