ASTG Coding Standard Recommended Coding Styles for Software Development in Fortran, C++, Java, and Python Version 1.7 ASTG January 20, 2015 CONTENTS CONTENTS Contents 1 Introduction 1 1.1 Purpose Of Conventions . .1 1.2 Why Use Conventions . .1 1.3 When NOT To Use These Conventions . .1 1.4 When To Use These Conventions . .1 2 Files 2 2.1 Naming Files . .2 2.1.1 Use Class/Module Name For File Name . .2 2.1.2 Extensions . .2 2.2 File Organization . .2 2.2.1 C/C++ Header Files . .3 2.2.2 C/C++ Source Files . .3 2.2.3 Fortran Files . .3 2.2.4 Java Files . .3 2.2.5 Python Files . .4 2.3 C++ Preprocessing . .4 2.3.1 Minimal Includes . .4 2.3.2 Brackets Verses Quotes . .4 2.3.3 Inclusion Protection . .4 2.3.4 Avoid Macros . .5 3 Formatting 5 3.1 Blank Space . .5 3.1.1 Blank Spaces . .5 3.1.2 Indentation . .6 3.2 Lines . .6 3.2.1 Line Length . .6 3.2.2 Line Continuation . .6 3.2.3 Single Blank Lines . .7 3.2.4 Double Blank Lines . .7 3.3 Fortran Free-Format . .7 4 Naming 7 4.1 Expressiveness and Scope . .7 4.2 Abbreviations . .7 4.2.1 Avoid Uncommon Abbreviations . .7 4.2.2 Use Mixed Case Acronyms . .8 4.3 Case and Underscores . .8 4.4 Naming Rules For Identifiers . .8 5 Declarations 9 5.1 Routines . .9 5.1.1 Verbs for Routines . .9 5.1.2 Accessors and Mutators . 10 5.1.3 Avoid Global Routines . 10 5.2 Variables and Arguments . 10 5.2.1 Use Nouns . 10 5.2.2 Proximity of Declaration . 10 ii ASTG Coding Standard v1.7 CONTENTS CONTENTS 5.2.3 Initialize Variables . 10 5.2.4 Zero Pointers . 10 5.2.5 One Declaration Per Line . 10 5.2.6 Avoid Literals . 11 5.2.7 Use Booleans for Booleans . 11 5.2.8 Descriptive Namelist Variables . 11 5.2.9 Avoid Global Variables . 11 5.2.10 Use Portable Numeric Types . 11 5.2.11 C++ Casting . 11 5.2.12 Use Argument Modifiers . 12 5.2.13 Use “Implicit None” . 12 5.2.14 Automate I/O “Unit Numbers” . 12 5.3 Classes, Modules and Types . 12 5.3.1 Use Pure Block Layout . 12 5.3.2 Fortran Derived Types . 13 5.3.3 Use Lowest Possible Scope . 14 5.3.4 Classes . 15 5.4 Use of External Units . 16 5.4.1 Use Explicit Namespace or Use-Module Items . 16 5.4.2 When To Use Namespaces . 16 5.4.3 Using “using namespace” Clause . 16 6 Structure and Control 17 6.1 Statements . 17 6.1.1 One Statement Per Line . 17 6.1.2 One Operation Per Statement . 17 6.2 Blocks . 17 6.2.1 Pure Block Layout . 17 6.2.2 Named Blocks . 17 6.2.3 Dummy Body Blocks . 18 6.2.4 Directives . 18 6.2.5 Case Statements (except in Python) . 18 6.3 Concurrency . 19 6.3.1 OpenMP and MPI . 19 6.4 Exception Handling in Java and C++ . 19 6.4.1 Use Judiciously . 19 6.4.2 Catch by Reference in C++ . 19 6.4.3 Constructor and Destructor Issues . 19 6.4.4 Re-throw the Same Exception in C++ . 19 6.4.5 Exception Handling in Java . 20 6.5 Prohibited Fortran Features . 20 7 Comments 20 7.1 Embedded Comments . 20 7.2 Comment Major Code . 21 7.3 Use Descriptive Comments . 21 7.4 Avoid In-line Comments . ..