[Courses] C Programming For Absolute Beginners, A note about indentation

[Jacinta Richardson]

G'day folk,

I'm just going to hijack Carla's course for a moment to talk to you about the 
single best programming practice you can have.  Oh there are lots of good 
programming practices that you should follow, but if there had to be a single 
most important one, it'd have to be indentation.

Indentation is a wonderful thing.

Much more important than coding for efficiency.  Much more important even than 
designing your code before you write it, or picking good variable names.  (Both 
of which are also pretty much essential.)  Good indentation will help you find 
bugs faster, and add fewer bugs into your code.

There are two kinds of indentation.  Vertical indentation - where we add 
newlines after each semi-colon/statement and preferably a blank line between 
code ideas, and you're all pretty good at this.    And Horizontal indentation, 
where we add extra whitespace in front of each statement each time we start a 
block, and some of you do not have the hang of this yet.

So, here are some examples.

This is my example from earlier with as little whitespace as I think I can get 
away with:

    // loopy, getting looped in C!  with more!
    #include<stdio.h>
    int main (){int a=0;int
    total=0;for(a=1;a<=50;a=a+1){total=total+a;printf("My running total is:
    %i\n",total);}printf("The sum of this loop is %i\n",total);return 0;}


It compiles and runs just fine.  But ew.  Very hard to read.

Here I've adding newlines, but nothing else.

    // loopy, getting looped in C!  with more!
    #include<stdio.h>
    int main (){
    int a=0;
    int total=0;
    for(a=1;a<=50;a=a+1){
    total=total+a;
    printf("My running total is: %i\n",total);
    }
    printf("The sum of this loop is %i\n",total);
    return 0;
    }


Again, it compiles and runs just fine.  None of your code is quite as bad as 
this.  Notice that we have two close curly braces in the same column.  This is 
confusing.  We have to go and actually read the code to see if the first one is 
closing main() or whether the second one closes main and the first one closes a 
loop or conditional.

Here I've added basic indentation.  4 spaces per block, before each statement:

    // loopy, getting looped in C!  with more!
    #include<stdio.h>
    int main (){
         int a=0;
         int total=0;
         for(a=1;a<=50;a=a+1){
             total=total+a;
             printf("My running total is: %i\n",total);
         }
         printf("The sum of this loop is %i\n",total);
         return 0;
    }

Again this compiles and runs just fine.  Now we can see that the final close 
curly brace closes the main() statement, because if we run our eyes up the 
column it's in, we "bump our head" on the i in "int main".  Likewise, at a 
glance, we can see that the second close curly brace closes the for() loop 
because if we run our eyes up the column its in we bump our head on the f in "for".

This code has the minimal amount of indentation we can afford to have.  If we 
were to forget to add one of those curlies, our code would look wrong.  We 
should never change an indentation level without an open or close curly (except 
if we're taking advantage of not needing braces for single statement 
loops/conditionals, but I don't recommend that).

We can now add some more whitespace to make the code look nice.   Here I'm 
adding some blank lines to break the code up into paragraphs.  Inside the main 
function my paragraphs are:

* initialise some variables
* calculate and print some values (in the for loop and after)
* return:

I've also added some whitespace around assignments, and function calls where I 
think it makes the code nicer to read.

    // loopy, getting looped in C!  with more!

    #include <stdio.h>

    int main () {
         int a     = 0;
         int total = 0;

         for( a = 1; a <= 50; a = a+1 ) {
             total= total + a;
             printf("My running total is: %i\n", total);
         }
         printf("The sum of this loop is %i\n", total);

         return 0;
    }


If I were to have if() statements in my code above, they'd be treated just the 
same way as that for loop.  eg

     for( a = 1; a <= 50; a = a+1 ) {
         total= total + a;

         /* Only print every 5th line (starting at 1) */
         if( a % 5 == 1 ) {
             printf("My running total at line %2d is: %4i\n", a, total);
         }
     }

In the above examples I've used K&R style bracing (where the open brace goes on 
the same line as the statement that is opening the block).   Carla has been 
demonstrating with gnu-style bracing (where the open brace goes under the first 
column of the statement that is opening the block).  Both styles have the close 
brace directly under the first column of the statement that opened the bloc.  
The full code in gnu-style (including that last if statement) looks like this:

    // loopy, getting looped in C!  with more!

    #include <stdio.h>

    int main ()
    {
         int a     = 0;
         int total = 0;

         for( a = 1; a <= 50; a = a+1 )
         {
             total= total + a;

             if(a % 5 == 1)
             {
                 printf("My running total at line %2d is: %4i\n", a, total);
             }
         }
         printf("The sum of this loop is %i\n", total);

         return 0;
    }

Either style is correct, unless you're working with pre-existing code, then the 
correct choice is to use whatever they've already been using.  So pick the style 
you prefer, but use it consistently, and remember to indent each line inside a 
block.

HOMEWORK: Correct the indentation on one of your previous exercises.

     J