Programming style: Improving the readability of your programs

Your first priority is likely to be that your program actually works! But you should also make your program readable and easy to understand. This will make it much easier to share your programs with other people (and to get help from them if you have problems). Moreover, you will often need to re-use a program some time after it is written. You can do this more easily if you don't have to spend a lot of time deciphering what you did a few weeks or months ago.

Following are some suggestions to help make your programs more understandable.

Variable names

Try to make your variables reflect what they actually mean. For example, if you are comparing yields for various crops you might have variables with names like SOY and MAIZE instead of X1 and X2 .

Blank spaces and lines

You can use blank spaces and lines to make your program clearer. The compiler ignores any blank spaces and blank lines (collectively termed "whitespace" by computer geeks). For example, the following three lines of code look the same to the compiler:

      PROGRAM MAIN

      PROGRAMMAIN

      PRO GRAMMA IN

Obviously, the first is easier to read. A less trivial example would be a mathematical formula:

      A=B-2.*C+4.*A*C-2.*A*B*C

As mentioned earlier, we can also use parentheses to group operations so that a formula is more readable. By combining the judicious use of blank spaces with parentheses, we can make the formula much easier to understand at a glance:

      A = B - (2. * C) + (4. * A * C) - (2. * A * B * C)

Comments

Comments are used to add notes that describe something about the program. You might insert comments near the beginning of your program that describe the overall purpose of the program, and other comments that explain specific parts of your calculations. Comments will be most useful if they resemble plain English (or whatever language you use from day to day). Avoid cryptic abbreviations and use normal capitalization instead of all-uppercase or all-lowercase letters.

Comments are displayed in your source code but are ignored when the program is run. Comments do not slow down the execution of your program.

In Fortran 77 a comment is indicated by the letter C in the first column. Some systems will accept other characters (such as an asterisk) to indicate comments, but keeping to the standard can avoid lots of headaches.

C   This is an example of a comment statement

Comments are easier to see if they stand out from the rest of the program:

• Use blank lines before and after the comments to separate them from the surrounding instructions.
• Start the text of your comments somewhere other than the 7th column, since most lines of your program will probably begin with the 7th column.

Example

      PROGRAM MAIN

C  This program computes the circumference and
C  area of a circle for a given radius.

      REAL PI
      REAL RADIUS, CIRCUM, AREA
      PI = 3.1416
      RADIUS = 5.
      CIRCUM = 2. * PI * RADIUS
      AREA = PI * RADIUS**2

C  Calculations are done. Print the results.

      PRINT *, 'THE RADIUS OF THE CIRCLE IS', RADIUS
      PRINT *, 'THE CIRCUMFERENCE OF THE CIRCLE IS', CIRCUM
      PRINT *, 'THE AREA OF THE CIRCLE IS', AREA

      STOP
      END

Compare with the following version of the same program, which does the exactly same thing but violates most of the rules for readability of programs:

      PROGRAM MAIN
C     HOMEWORK
      REALAA,A1,A2,A3,A4
      A2=5.
      A1=3.1416
      A4=2.
      A3=A4*A1*A2
      AA=A1*A2*A2
      PRINT*,A2,A3,AA
      STOP
      END

Assignment:

Use the suggestions given above to improve the readability of the program you wrote in lesson 6.

Next: Conditional execution

Back to the main page for the programming tutorial.