Apr 20, 2023

Indentation& Comments

Overview

Indentation isn't important to the correctness of your programs (the computer totally ignores it), but it can make a big difference to the readability of your programs.

Version without indentation

method main(){Jeroo Sally = new Jeroo();while(!Sally.isWater(AHEAD)) {Sally.hop();}Sally.turn(RIGHT);while(!Sally.isWater(AHEAD)) {Sally.hop();}Sally.turn(RIGHT);while(!Sally.isWater(AHEAD)) {Sally.hop();}Sally.turn(RIGHT);while(!Sally.isWater(AHEAD)) {Sally.hop();}Sally.turn(RIGHT);} What d

oes it

do???

with indentationmethod main()

{    Jeroo Sally = new Jeroo();    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);}

the meaning is easier to

see

add in commentsmethod main()

{    Jeroo Sally = new Jeroo();

    // Go along the top (north) edge of the island    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);

    // Go along the right (east) edge of the island    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);

    // Go along the bottom (south) edge of the island    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);

    // Go along the left (west) edge of the island    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    // Note that this last turn is needed to ensure that Sally is facing east    // again, as required in the problem statement.    Sally.turn(RIGHT);}

now, anyone could look at the program and know exactly what it does.

Comments describe what is happening in the program

method main(){    Jeroo Sally = new Jeroo();

    // this is a loop    while(!Sally.isWater(AHEAD)) {

        Sally.hop();    }    Sally.turn(RIGHT);

    // this is a loop    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);

    // another loop    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);

    // still looping    while(!Sally.isWater(AHEAD)) {

        Sally.hop();    }    // a turn

    Sally.turn(RIGHT);}

NOT stating the obvious

These are lousy comments!

refining further…

of course, there are areas of repeated code… perfect candidates for creating methods how would you rewrite it to be more efficient using

methods? can you still create a program as readable as the

example given here?

add in commentsmethod main()

{    Jeroo Sally = new Jeroo();

    // Go along the top (north) edge of the island    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);

    // Go along the right (east) edge of the island    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);

    // Go along the bottom (south) edge of the island    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    Sally.turn(RIGHT);

    // Go along the left (west) edge of the island    while(!Sally.isWater(AHEAD)) {        Sally.hop();    }    // Note that this last turn is needed to ensure that Sally is facing east    // again, as required in the problem statement.    Sally.turn(RIGHT);}

Repeated code makes a good method

This could be a method

Or would this be a better choice for a method?

The End

The important point is to make a reasonable effort to communicate to your human readers as well as to the computer.

Comments and indentation are the 2 tools for making a program readable