[Sussex] Code-writing methods

[Steven Dobson]

Nic

On Thu, 2006-11-16 at 17:04 +0000, Nic James Ferrier wrote:
> "Neil Hart" <neil.m.hart at googlemail.com> writes:
> 
> > Any non-programmer, or someone not familiar with the language syntax
> > will immediately see what is going on in the code.  The penalty for
> > such an approach is unusually long variable names and lots of
> > #defines, but in my view, this is not a big price to pay.
> 
> #defines??? so 1980s. We have const's now nearlly everywhere.
> 
> 
> Sherioushly, I believe this is the best advice. Comments are actually
> harder to write than code.

Not quite:  Good comments are harder to write than code.  Bad comments
that tell you no more than the code are very easy to write (I saw stuff
like this on the first project I was on):

    //  Procedure bubble_sort
    //
    //  Author:  Joe Bloggs
    //
    procedure bubble_sort(DATA array)
    begin
        BOOLEAN continue := false;

        // loop start
        do
            // Initialise the loop
            i := 1;

            // Initialise continue
            continue := false;

           // Loop until the limit is reached
           while (i < (ARRAY_SIZE - 1))
           begin
        
                // compare elements
                if (data[i] > data[i+1])
                being
                    // set temp to first element
                    temp := data[i];

                    //set first element to second element 
                    data[i] := data[i+1];

                    // set second element to temp
                    data[i + 1] := temp;

                    // set continue to true
                    continue := true;
                end;

               // Increment i
               i := i + 1;
           end

        // Loop end
        while (continue);

    // procedure end
    end

The only thing that give you a clue as to what the code is trying to do
is the procedure name:  it is trying to implement a bubble sort (a
standard computer method for sorting an array of data).  Note how the
comments just tell you exactly the same thing as the line of code that
follows.

If you comment what you are trying to do then anyone come after can see
if you made a mistake.  I offer this and an example of better
commenting.  If you find it clearer as to how the procedure works it
because the comments make it so - I haven't change one line of code!

    //  Sort an array of data using the bubble sort algorithm
    //
    //  Author:  Joe Bloggs
    //
    procedure bubble_sort(DATA array)
    begin
        BOOLEAN continue := false;

        // keep repeating until the array is in order
        do
           // Start at the the first element of the array to be sorted
           i := 1;

           // Assume that the array is in order (our exit condition)
           continue := false;

           // loop though the array comparing each element with the one
           // after it (swapping where necessary)
           while (i < (ARRAY_SIZE - 1))
           begin
        
                // compare adjunct elements for order
                if (data[i] > data[i+1])
                being
                    // Elements are out of order

                    // Swap
                    temp := data[i];
                    data[i] := data[i+1];
                    data[i + 1] := temp;

                    // It will be necessary parse the array at least
                    // one more time
                    continue := true;
                end;

               // Proceed to the next element in the array
               i := i + 1;
           end

        // Repeat until no swapping is performed and therefore the 
        // array is in order
        while (continue);

    end 

> I reiterate: code *is* communication.

Agreed.  But by itself it is incomplete.  Code can never tell what a
program is trying to do only how it is attempting to do it.  I therefore
believe that comments should be used to impart this vital piece of
information to those that come after me (and me as one soon forgets!).

Steve


-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
Url : http://mailman.lug.org.uk/pipermail/sussex/attachments/20061116/ca9994ae/attachment.pgp