• Introduction
• Instructions for adding software to the CVS repository
  
• Program Development and Design
• Coding Style

Introduction

• Improvements to the basic PARAMESH kernal software found in the mpi_source, source and hearders directories.
• Software the addes additional functionality to PARAMESH.  This type of software should be added as separate entities within the utilities directory.

• Maintainability - refers to how easy it is to understand the purpose of each element of the program, and to modify and extend the program.
  
  
• Portability - refers to how easily the program can be ported to new computational platforms.
  
  
• Efficiency - refers to the amount of computer resources (CPU time, memory, disk storage, etc.) required to run the program.

Much of this material has been taken, sometimes verbatim, from the following documents:

• Levine, David L., "Fortran 77 Coding Guidelines"
• Huddleston, John, "Fortran Coding Standard"
• Robey, Tom, and Smith, Brian, eds., "Future of Fortran - Moving from F77"
• Andrews, Phillip; Cats, Gerard; Dent, David; Gertz, Michael; and Ricard, Jean Louis, "European Standards For Writing and Documenting Exchangeable Fortran 90 Code"
• Towne, Charlie, "Programming Guidelines for the NPARC Alliance Software Development", http://www.grc.nasa.gov/WWW/winddocs/guidelines/pgmstds.html
  

1. Before checking anything in send an e-mail to Kevin Olson or Peter MacNeice describing your changes and also copies ot the files with the changes you have made.  Describe how we can run you contributed test program.  We will review the changes and then let you know if you can check them in or if you need to make further changes.  Please don't check in until we give you the OK to do so.
2. Once you get the OK, go ahead and check them in.
3. Add a few descriptive lines in the ChangeLog file of your changes or additions and check in this file.
   
4. <>If you are contributing a new PARAMESH utility (in the paramesh/utilities directory) then these following additional steps should be followed,
   

• Provide a script that installs your software somewhere in the PARAMESH source code kernal (in mpi_source or source). (See the existing install scripts for the code which is in the paramesh/utilities directory).
  
• Write a Makefile or make sure that your installation script edits the Paramesh Makefiles for compiling and linking your code.
  
• DO NOT embed compiler directives in the code.
  
• Provide a short test code which specifically tests your software contribution.  Make sure it gets installed into the Tests directory by your INSTALL script and that the Makefile in Tests gets edited to include your test code.
  
• Provide a README file with your software that explains what it does, how to use it, how to install it and how to run your test program.
  
• Include the standard PARAMESH license header in each file of your contributed code.
  

Program Development and Design

Items in this section are fairly general and fundamental in nature. They impact all three of the items listed above - maintainability, portability, and efficiency.

Language

Try to use ANSI standard Fortran 90 exclusively.  If you must, you can use C or C++, but it must work with PARAMESH and be callable from a Fortran 90 program.

Organization

• Write modular code.
• In general, put each subprogram in a separate file, using the subprogram name as the file name, with a .F90 extension.
• Within each routine, use interface blocks to explicitly specify the interface to your contributed routines.  
• Group related files in a single directory.
• Names of files and directories should reflect their purpose.

Common Blocks

• Don't use common blocks, use Modules instead.  Period !

Data Types

• Use Implicit none in each program unit, and explicitly declare all variables and parameters. Common variables and parameters should be declared in the relevant include file.
• Don't use *'ed forms, like Real*8.  Declare variables using Real :: 
• Don't compare arithmetic expressions of different types; convert the type explicitly.

Dynamic Memory

• Assign memory for arrays dynamically, using automatic arrays, allocatable arrays, and/or array pointers. Explicitly deallocate memory used by allocatable arrays and array pointers when they're no longer needed. 

Coding Style (see mpi_source/mpi_amr_guardcell.F90 for a complete example)

Items in this section are fairly specific, and primarily impact the readability, and thus the maintainability, of the final product. It is recognized that rules for "good coding style" are somewhat subjective. 

Program Units

• Begin main programs with a Program statement.
• Don't use multiple entries or alternate returns.
• Use the intent attribute in the type declaration statement for all variables passed into our out of subroutines and functions.  Make sure to include these in the interface block that you create for the surbroutine.
  
• Match the arguments in the calling (sub)program to those of the called subprogram in both number and type.
• Use the following order for statements within each subprogram:
  • Standard header section.  This should be comments in the format used with the robodoc code documenation software (See the PARAMESH source code for examples).
    
  • Use modules
  • Parameter definitions
  • Type declarations for subprogram arguments
  • Type declarations for local variables
  • Executable code
• Functions should not have side effects. (I.e., don't change the arguments or any common variables inside the function.)
• Use generic names for library functions, rather than precision-specific ones.
• Name external functions in an External statement.

Statement Form

• Use free-form formatting, but for readability:
  • Keep line lengths below 80 characters.
  • Start each line in column 7 or higher.
  • Reserve columns 1-5 for statement labels.
  • Don't use the optional continuation character (i.e., &) at the start of continuing lines. Avoid splitting keywords and character strings between lines.
  Note that with free-form formatting, an & must be the last character (except for comments) in a line that is to be continued.
• Use a ! in column 1 for non-blank comment lines.
• Split long lines before or after an operator, preferably a + or -.
• Don't write more than one statement per line.

Statement Labels

• Minimize the use of statement labels, where appropriate.
• Don't use unreferenced labels.
• Use labels in ascending order.

Upper/Lower Case

• Use upper case for parameters, upper case for subrotines and functions from libraries outside of PARMAESH (such as MPI), lower case with an initial capital letter for Fortran keywords, and lower case for everything else except comments and character strings.
• Write comments as normal text, with normal capitalization rules.

Spacing

• Use spacing to enhance readability.
• Indent contents of code blocks (i.e., do loops, block if, etc.). Suggested amount is three spaces.
• Don't use tabs.
• Use spacing in equations to clarify precedence of operators. I.e., normally put one space on either side of =, +, and - operators (except in subscripts), but none around *, /, or ** operators. For example, this:

        y1 = (-b + Sqrt(b**2 - 4.*a*c))/(2.*a)
  

  is easier to read than this:

        y1=(-b+Sqrt(b**2-4.*a*c))/(2.*a)
  

  or this:

        y1 = ( - b + Sqrt ( b ** 2 - 4. * a * c ) ) / ( 2. * a )
  

• Use spacing to reveal patterns in continuation lines and in separate but logically related statements. For example, this:

        dum1 = Sqrt((fr (i,j) - fr ( 1, j))**2 + &
                    (fth(i,j) - fth( 1, j))**2)
        dum2 = Sqrt((fr (i,j) - fr (n1, j))**2 + &
                    (fth(i,j) - fth(n1, j))**2)
        dum3 = Sqrt((fr (i,j) - fr ( i, 1))**2 + &
                    (fth(i,j) - fth( i, 1))**2)
        dum4 = Sqrt((fr (i,j) - fr ( i,n2))**2 + &
                    (fth(i,j) - fth( i,n2))**2)
  

  is easier to read than this:

        dum1 = Sqrt((fr(i,j) - fr(1,j))**2 + (fth(i,j) - &
        fth(1,j))**2)
        dum2 = Sqrt((fr(i,j) - fr(n1,j))**2 + (fth(i,j) - &
        fth(n1,j))**2)
        dum3 = Sqrt((fr(i,j) - fr(i,1))**2 + (fth(i,j) - &
        fth(i,1))**2)
        dum4 = Sqrt((fr(i,j) - fr(i,n2))**2 + (fth(i,j) - &
        fth(i,n2))**2)
  

Variable Names

• Use names that are descriptive of the entity being represented, and/or are consistent with the standard notation in the field.
• In general, follow standard Fortran convention for the variable type. I.e., integers start with i, j, k, l, m, or n, all others are real.
• Don't use keyword, subprogram, or module names for variables.
• Don't give a local variable the same name as any common variable.

Arrays

• Dimension arrays in the type declaration statement, not in a separate Dimension statement.
• When passing character variables into a subprogram, use the assumed-length form in the type declaration statement inside the subprogram. I.e.,

        Subroutine sub (c)
        Character*(*) c
  

• Don't exceed the bounds of the array dimensions.

Control Statements

• Short do loops may be written using simple Do and End do statements, without labels.
• Long do loops and if blocks (more than a page or so), should mark the end of the construct in some way that "connects" it with the start. One convenient and readable method is to use an in-line comment on the ending statement that repeats the beginning statement. E.g.,

        If ( bccode == 13 ) then
  
           [Lines and lines of code]
  
           Do i = 1,nzones
              If ( zondim(1,i) > 0 ) then
  
                 [More lines and lines of code]
  
              End if   ! If ( zondim(1,i) > 0 ) then
           End do      ! Do i = 1,nzones
        End if         ! If ( bccode == 13 ) then
  

  
  
• Minimize the use of Go to statements, especially where they can be replaced by short'ish if blocks, but don't create convoluted code just to avoid using them. Don't be afraid to use a Go to where it makes sense. An example might be a long (more than a page) conditional section of code. In this case a well-commented Go to block, which ends with an easily-noticed statement label, may be more readable than an indented if block without an ending statement label. Also consider making a long conditional section a separate subprogram.

<>Capitalize the entire subroutine name when making the call to the libary routine, e.g.
Call MPI_BARRIER(MPI_COMM_WORLD,ierr)

Comments

• Use comments liberally to describe what's being done. Where code may be confusing, use longer comments to describe why something's being done the way that it is.
• Make each comment meaningful; don't simply re-iterate what's already obvious from the coding itself. As an obvious example, this:

  !-----Fill the guardcells of all PARAMESH blocks
        Call amr_guardcell
  

  is more meaningful than this:

  !-----Call amr_guardcell
        Call amr_guardcell
  

• Use a consistent method to help the reader distinguish comments from code, such as the "-----" leaders in the examples above.
• Start the text of comments at the same indentation level as the code being described.
• Use a standard header section at the beginning of each subprogram defining its purpose.
• Use in-line comments, with ! as the delimiter, where appropriate for short explanations or clarifications. Start in-line comments far enough to the right (e.g., three spaces or more from the end of the statement) to help distinguish comments from code. Where appropriate, align them vertically with nearby in-line comments.
• Define each common block variable using an in-line comment on its type statement in the include file. Each common variable will thus have a separate type statement.
• Define key local variables using in-line comments on the type statements in the subprogram.

Obsolete/Forbidden Features

The following Fortran features are either formally declared as obsolete, or widely considered to be poor programming practice, and should not be used:

• Arithmetic if statements
• Do loops with non-integer indices
• Shared do loop termination statements
• Pause statements
• Assigned and computed Go to statements
• Hollerith edit descriptors and Hollerith character strings
• Equivalence statements
• Alternate return statements