RFP_ATT_D_TRACE_Standard_F90.pdf

Attachment D

TRACE Standard F90 Programming Practices and General Design Philosophies

Developers shall adhere to these practices for all new coding. Please send feedback to Christopher.Murray@nrc.gov. Improper style in old coding will be corrected as resources permit.

* Write GOOD requirements - see http://www.incose.org/workgrps/rwg/writing.html for some online guidelines

* All code SQA reports and code documentation shall be prepared and submitted to NRC in Framemaker format. Equations shall be generated using Framemaker's built-in equation tools. Line and vector-based diagrams shall be generated using Framemaker's built-in drawing tools. In cases where this is not possible, the original picture files shall accompany the document and be in a format editable by common drawing tools (eps, svg, mif, pdf, cdr). Use encapsulated postscript (eps) only as a very last resort - we expect developers to employ modern drawing tools that will not lead to this limitation. For engineering plots, AptPlot is the preferred program for generating such plots. Save them to mif format for importing into a Framemaker document. Plots shall NOT be imported as bitmap images (use vector formats instead. For raster/bitmap pictures, the image may be inserted directly into the document, but the transmittal shall include the image in its own file in a standard format (gif, png, or jpg).

* All new variables will be explicitly typed, and all new routines shall include IMPLICIT NONE statements.

* Implement a standard KIND representation for Integers and Reals

+ Always insert the line "USE IntrType" after the MODULE statement, or for any subprograms that are not module procedures, after the SUBROUTINE or FUNCTION statement. If IntrType is declared at the module level, there is no need to include it within the CONTAINed subroutines.

+ Begin all definitions of real variables with "REAL(sdk)"

+ Begin all definitions of integer variables with "INTEGER(sik)"

* All use of real and integer constants should be implemented with the _sdk and _sik kind type parameters

+ For example, use 2_sik instead of just 2, or 1.0e+10_sdk instead of 1.0d+10, etc.

* Do not use continuation lines inside of variable declaration statements

* When declaring a variable of TYPE POINTER, ALWAYS initialize it with the => NULL() syntax.

* Get in the habit of using default initialization whenever variables are declared, but keep in mind that use of this syntax implies the SAVE attribute for any variable for which this is done.

Developers shall use the ONLY syntax in their USE statements. This prevents unintended variables from coming into scope and preventing the compiler from detecting instances where a local variable is undeclared or an unintended global variable is used mistakenly (as can happen with variables like cco when cutting and pasting code).

* Developers shall use object-oriented designs. What does this imply? It means that coding shall be data-centric. In other words, design the data structure first. Make it flexible enough to handle all possible situations for which you could ever envision needing it. Once an effective data structure is fleshed out, on paper, begin to think about methods that operate on that data structure. As a minimum, there ought to be constructor/initialization and destructor methods for the data structure as a whole and any substructure pointer or allocatable arrays that might exist. Make the data structure PRIVATE to the module of interest. Access to the data structure shall only be through subroutines or functions. The contractor shall factor these ideas into proposals and predictions about time and cost. The penalty with these sorts of designs is in run-time speed, so there may be situations where such designs do not make sense but a developer's priorities shall be object-oriented first, run-time second. Speed can always be recaptured in the next generation of processors or by optimizing other aspects of the code.

* All dummy arguments and important local variables shall be declared within their own TYPE declaration statements.

* The INTENT of all dummy arguments shall be declared in all new coding

* Do not use bare END statements

* All Fortran statements, attributes, intrinsic subprograms, and logical operators in new coding shall be in all upper case.

REAL(sdk), POINTER, DIMENSION(:,:) :: a, aa

IF ( i.GT.j ) THEN

* Leading and trailing underscores shall not be used in any names (due to the potential for name mangling issues during linking), but underscores in the middle of names are allowed.

* Variable, file, and procedure names shall be long enough to be self-documenting, within reason, with a suggested limit of 15-20 characters

* All new variable names shall have the first letter of each sub-element capitalized except the first, as in pipeData.

* All derived type names shall end in "T", as in pipeDataT.

* Module and subprogram names shall begin with a capitalized letter, but don't change old subprogram names.

* All new coding shall be structured with an indentation level of three spaces.

DO i = 1,n

DO j = 1,n

IF (i.gt.j) THEN a(i,j) = - aa(j,i)

ELSE

a(i,j) = aa(i,j)

ENDIF

ENDDO

ENDDO

* Use IF-THEN-ENDIF instead of IF (condition) statement

* "GOTO" statements shall be used sparingly, if at all. Instead, programmers shall use IF-THEN-ELSE, SELECT CASE, CYCLE, EXIT, and internal subprograms as appropriate

* Use standard F90 free format code style with the following exceptions:

+ A limit of 110 columns per line

+ Source code shall start in column 7. Columns 1-6 are to be reserved for statement labels. This does not apply to comments and MODULE statements.

* Comments lines shall be indicated with a "!" in column 1.

* Comments that serve to delineate, summarize, and/or clarify larger multi-step algorithms shall be indented one or two spaces.

* Comments that serve to clarify the intent of and/or summarize small blocks of code shall be given the same indentation level as that code.

* Comments shall be offset by at least one blank line from the previous F90 statement.

* Comment shall not be placed at the end of a continued line (illegal Fortran).

Try not to ever use multi-line statements. It makes writing scripts to parse FORTRAN more difficult and invalidates line coverage profiling studies.

* End-of-line comments shall not be used except in context of data type declaration statements or where a brief comment on the same line as the statement clearly accentuates and improves the readability and intent of the IF statement or block that follows, ala

INTEGER(sik) :: height = 0.0_sdk ! height of the cell or

IF (fillTab(cco)%flowin .GE. 0.0d0) THEN !Determine donor cell mixture.

* Comment blocks shall generally not be longer than a dozen lines (additional information can go in the programmer's manual, and/or the SDID subroutine report).

* Authorship information shall be included for each new subroutine that a developer creates or rewrites from scratch. When well defined blocks of changes (on the order of

100 lines or more) are made to an existing subroutine, a note shall be placed directly beneath the existing authorship info (or below the subroutine purpose if it does not) denoting the name, organization, date and quick description of the modifications.

Authorship info shall not be provided when the changes are spread out (i.e. not in well defined blocks) - even if they significantly modify some behavior of the algorithm contained therein - although the subroutine description shall be checked for accuracy and modified when appropriate.

* The following standard template shall be used for each new subroutine that is developed (a plug-in to Visual Fortran has been created which can create this automatically):

SUBROUTINE SampleSub() USE IntrType

IMPLICIT NONE

! The purpose of this routine is to <<Insert Description here>> ! Programmed by Name, Organization, Date (Month/Year) ! Subroutine Argument Descriptions:

! Variable Declarations:

RETURN

END SUBROUTINE SampleSub When making a change, do not comment out the old coding but instead delete it.

* Do not surround your coding with your initials - it just uglifies the code.

* Never use COMMON. Use a MODULE and corresponding USE instead.

* Never use EQUIVALENCE. Use POINTERs if you must, but better practice is to redesign so pointers are not necessary.

* All code shall be standard F90 - use of non-standard compiler extensions or preprocessor definitions shall not be allowed.

* If available in the compiler, all code shall be developed with strict F90 standards checking and array bounds checking turned on. Also, compiler flags shall be engaged which check for any unused variables and uninitialized variables. If any unused variables are located in a routine that a developer touches, then he or she shall remove them.

* If a new subroutine is added to the code outside the scope of a MODULE statement, then an explicit interface to that routine shall be created. This allows the compiler to handle checking of the argument lists at compile time.

* Developers shall remove any unused subroutines which are created as a result of their efforts.

* When incorporating legacy code from other computer codes into TRACE, every effort shall be made to clean that code up and to ensure that it conforms to the stylistic rules and design philosophies outlined in this document.

When preparing an SRD for a particular development project, the requirements shall take into account the planned update's effect on or interaction with such areas as:

+ restart processing

+ CSS controllers

+ control system

+ exterior component and other parallel programming interfaces

+ timestep backup flow logic

+ SNAP and/or VEDA + English units

* Any modification or enhancement of intercomponent transfer of information shall never involve direct modification of bd array elements. All transfers shall be arranged during the initialization phase of the calculation (module SysService) through the system service transfer tables.