Next:
Contents
Contents
Earth System Modeling Framework
Software Developer's Guide
Silverio Vasquez, Sylvia Murphy, and Cecelia DeLuca
October 16, 2009
Contents
1 Introduction
1.1 About this Document
1.2 Supplementary Information
1.3 Acknowledgments
2 Groups and Roles in ESMF Development
2.1 Core Team
2.1.1 Core Team Roles
2.2 Joint Specification Team (JST)
2.3 Change Review Board (CRB)
2.4 Quality Assurance Responsibilities
3 Collaboration Environment and Communication
3.1 Mailing Lists
3.2 Meetings and Telecons
3.3 SourceForge Open Source Development Environment
3.3.1 The Main ESMF Site and Repository
3.3.2 The ESMF Contributions Site and Repository
4 Processes
4.1 Software Process Model
4.2 ESMF Process History
4.2.1 Software Concept
4.2.2 Requirements Analysis
4.2.3 Architectural Design
4.3 Ongoing Development
4.3.1 Telecon Etiquette
4.3.2 Design Reviews
4.3.3 Implementation and Test Before Internal Release
4.3.4 Implementation and Test Before Public Release
4.3.5 Code Check-In
4.3.6 Code Reviews
4.3.7 Releases
4.3.8 Backups
4.4 Testing and Validation
4.4.1 Unit Tests
4.4.1.1 Writing Unit Tests
4.4.1.2 Analyzing unit test results
4.4.1.3 Disabling unit tests
4.4.2 Examples
4.4.2.1 Disabling examples
4.4.3 System Tests
4.4.3.1 Writing System Tests
4.4.3.2 Disabling system tests
4.4.4 Test Harness
4.4.4.1 Specifying Tests Harness tests
4.4.4.2 Analyzing Test Harness results
4.4.5 Use Test Cases (UTCs)
4.4.6 Beta Testing
4.4.7 Automated Regression Tests
4.4.8 Testing for Releases
4.5 User Support
4.5.1 Roles
4.5.2 Support Categories
4.5.3 Summary Work Flow
4.5.4 General Guidelines for Handling Tickets
4.5.5 esmf_support@ucar.edu Mail Archives
4.5.6 INFO:Code (subject) mail messages
4.5.7 freeCRM
4.5.8 Annual Code Contact
4.5.9 Dealing with Applications that use ESMF
5 Test Harness
5.1 Test Harness Structure
5.2 Specification of Test Configuration
5.2.1 Top level helper file
5.2.2 Problem descriptor file
5.2.3 Problem descriptor string syntax
5.2.3.1 Grid syntax
5.2.3.2 Distribution syntax
5.2.3.3 Transformation method
5.2.3.4 Staggering syntax (Not currently implemented)
5.2.4 General Data Structures
5.2.5 Specifier files
5.2.6 Grid Specification
5.2.6.1 Curvilinear Grid Coordinate Generation (For Future Implementation)
5.2.6.2 Specifier file syntax for redistribution
5.2.6.3 Specifier file syntax for regridding
5.2.7 Distribution Specification
5.2.8 Class Specification
5.3 Reporting test results
6 Conventions
6.1 Docs: Code and Documentation Templates and Associated Scripts
6.1.1 Documentation Generation Script
6.1.2 Code Generation Scripts
6.2 Docs: Documentation Guidelines and Conventions
6.2.1 Accessibility
6.2.2 File format
6.2.3 Typeface and Diagram Conventions
6.2.4 Style Rules for L
A
T
E
X
6.3 Docs: Performance Report Conventions
6.4 Docs: Reference Manual Conventions
6.4.1 Description, Use and Examples, and Other Introductory Sections
6.4.2 Examples Sections
6.4.3 Flags and Options Sections
6.4.4 Class API Sections
6.5 Code: Method Conventions
6.5.1 Standard Method Names
6.5.2 Use of *Set and *Get
6.5.3 Use of Is* and Has*
6.5.4 Functions vs. Subroutines
6.5.5 Source and Destination Ordering
6.6 Code: Argument Conventions
6.6.1 Standard Variable Names
6.6.2 Use of Is* and Has*
6.6.3 Variable Capitalization
6.6.4 Variables Associated with Options
6.6.5 Variables Having Logical Data Type
6.7 Code: File Rules
6.7.1 Version Identification
6.7.2 License and Copyright Information
6.7.3 TODO: Reminder
6.8 Code: Style Rules for Source Code
6.9 Code: Error Handling Conventions
6.9.1 Objectives
6.9.2 Approach
6.9.3 Error Masking
6.9.4 Example (pre-review method)
6.9.5 Example (post-review method)
6.10 Initialization Standardization Instructions
6.10.1 Overview
6.10.2 Instructions
6.10.3 Module
6.10.4 Shallow Class
6.10.5 Deep Class
6.10.6 Parameter Class
6.10.7 Subroutine
6.10.8 ESMF Class Types
6.11 Code: Data Type Consistency Guidelines
6.11.1 Use ESMF names for data types in C and ESMF data kinds in Fortran
6.11.2 Fortran
6.11.3 C and C++
6.11.4 ESMF_TypeKind ``labels'': When knowing the data type/kind is necessary
6.11.5 Guidelines for Fortran-C Interfaces
6.12 Code: Optional Argument Conventions for the C/C++ API
6.12.1 Overview
6.12.2 Approach
6.12.3 Internal Macros for Processing the Optional Argument List
6.12.4 Parsing the Optional Argument List
6.13 Code: Makefile Conventions
6.13.1 Code Building Rules
6.13.2 Document Building Rules
6.13.3 Include Files
6.14 Preprocessor Usage
6.14.1 Using the Preprocessor For Generic Fortran Code
6.14.2 System Dependent Strategy Using Preprocessor
6.15 ESMF Data Type Autopromotion Support Policy and Guide
6.15.1 How We Arrived at This Autopromotion Support Policy
6.16 Scripts: Script Coding Standard
6.16.1 Content Rules
6.17 Lang: Interlanguage Coding Conventions
6.18 Lang: Fortran Coding Standard
6.18.1 Content Rules
6.18.2 Style Rules
6.19 Lang: C/C++ Coding Standard
6.20 Repo: Source Code Naming and Tagging Conventions
6.20.1 Public Releases
6.20.2 Internal Releases
6.21 Data Management Conventions
7 Tracking and Metrics
7.1 Release Schedule
7.2 Task List
7.3 Trackers
7.3.1 Setting Ticket Priorities
7.3.2 Labeling Tickets Longer than 2 Weeks
7.3.3 Estimating Ticket Completion Time
7.3.4 Labeling Tickets with Time Estimates
7.3.5 Cross-Referencing the Task List and Trackers
7.3.6 Summary
7.3.7 Types of Trackers
7.4 Metrics
7.4.1 Unit and System Tests Coverage
7.4.2 ESMF Requirements Coverage
7.4.3 Source Lines of Code, SLOC
8 Policies
8.1 External Software Libraries
8.2 Graphics Packages
Appendix A: Testing Terminology
Bibliography
About this document ...
esmf@ucar.edu
