Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Adds documents for guidelines on contributing #149

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Adds documents for guidelines on contributing #149

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9f77367
Adds documents for guidelines on contributing
thomas-robinson Sep 27, 2024
b4cad77
Updates for documentation clarity
thomas-robinson Sep 30, 2024
b55a7cf
Clarification in style for multi word variable names
thomas-robinson Sep 30, 2024
9ae9cfd
Documentation clean up
thomas-robinson Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
69 changes: 69 additions & 0 deletions CODE_OF_CONDUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
# Code of Conduct

## Our Pledge

In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, sex characteristics, gender identity and expression,
level of experience, education, socio-economic status, nationality, personal
appearance, race, religion, or sexual identity and orientation.

## Our Standards

Examples of behavior that contributes to creating a positive environment include:

* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members

Examples of unacceptable behavior by participants include:

* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others’ private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting

## Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.

Project maintainers have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, or to ban temporarily or permanently any
contributor for other behaviors that they deem inappropriate, threatening,
offensive, or harmful.

## Scope

This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting the project team at [email protected]. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.

Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project’s leadership.

## Attribution
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
285 changes: 285 additions & 0 deletions CODE_STYLE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,285 @@
# Coding Style

## General

* Trim all trailing whitespace from every line (some editors can do this
automatically).
* No <Tab> characters.
* Supply a header for each file with a description of the file and the author(s)
name or GitHub ID.
* A copy of the [Gnu Lesser General Public License](https://www.gnu.org/licenses/lgpl-3.0.en.html)
must be included at the top of each file.
* Documentation should be written so that it can be parsed by [Doxygen](http://www.doxygen.nl/).
* All variables should be defined, and include units. Unit-less variables should be marked `unitless`
* Provide detailed descriptions of modules, interfaces, functions, and subroutines
* Define all function/subroutine arguments, and function results (see below)
* Follow coding style of the current file, as much as possible.

## Fortran

### General

* Use Fortran 95 standard or newer
* Two space indentation
* Use `KIND` parameters from platform_mod of libFMS
* Never use implicit variables (i.e., always specify `IMPLICIT NONE`)
* Lines must be <= 120 characters long (including comments)
* logical, compound logical, and relational if statements may be one line,
using “&” for line continuation if necessary:
```Fortran
if(file_exists(fileName)) call open_file(fileObj,fileName, is_restart=.false)
```
* Avoid the use of `GOTO` statements
* Avoid the use of Fortran reserved words as variables (e.g. `DATA`, `NAME`)
thomas-robinson marked this conversation as resolved.
Show resolved Hide resolved
* Avoid the use of `COMMON` blocks

### Derived types

* Type names must be in CapitalWord format.
* Variables names must be in underscore_word format.
thomas-robinson marked this conversation as resolved.
Show resolved Hide resolved
* All member variables must be private.
* Doxygen description on the line before the type definition.
* Inline doxygen descriptions for all member variables.

## Functions
* If a function has a result variable, it should be declared on its own line,
and the variable should not be declared with a specific intent.
* Inline doxygen descriptions for all arguments, except the result variable.
* Doxygen description on the line(s) before the function definition. This must
specify what the function is returning using the `@return` doxygen keyword.

## Blocks
* terminate `do` loops with `enddo`
* terminate block `if`, `then` statements with `endif`
* Label large blocks or multiple nested blocks

## OpenMP

* Directives should start at the beginning of the line, and be in lowercase.
* All openMP directives should specify default(none), and then explicitly list
all shared and private variables.
* All critical sections must have a unique name.

## Precision
* Precision of all real arguments are explicitly defined as `real(kind=r4_kind)`,
`real(kind=r8_kind)`, or as any other precision parameters defined in platform_mod of libFMS.
* The precision of real numerical values should be consistent with the precision
of the associated variable. For example, if the variable `a` has been declared
as r8_kind, then `a=1.4_r8_kind` is acceptable. The following, a=1.4 and a=(1.4,kind=r8_kind),
are not acceptable since the numerical value of 1.4 will be represented in the default precision
set by the compiler.
* The precision of integers do not need to be explicitly defined and can be determined at compile time.
* If the precision of integers are explicitly defined, they are defined with the precision parameters,
_e.g._ i4_kind, i8_kind, found in platform_mod of libFMS.

## Macros
* All letters in the macro names are capitalized
* All macro names end with an underscore "_"
* All precision related macro names start with the letters "FMS"
* Macro names should be unique to each module. For example,
`FMS_AU_KIND_` is used in axis_utils_mod.
`FMS_HI_KIND_` is used in horiz_interp_mod

## .fh and .inc files
* The .fh header files contain macro definitions.
* If the .fh files contain mainly precision related macro definitions, the files
should be named with `_r4.fh` and `_r8.fh` extensions in the include subdirectory found
bensonr marked this conversation as resolved.
Show resolved Hide resolved
in the module directory. These .fh files are `#include`-ed at the end of the .F90 module files.
* For precision related .inc files, the .inc files contain the procedure definitions and are
`#include`-ed at the end of both *_r4.fh and *_f8.fh files. These .inc files are located in the
same include subdirectory as the .fh files. See below for details.
## Fortran Example

```Fortran ./example.F90 file

!***********************************************************************
!* GNU Lesser General Public License
!*
!* This file is part of the GFDL Flexible Modeling System (FMScoupler).
!*
!* FMScoupler is free software: you can redistribute it and/or modify it under
!* the terms of the GNU Lesser General Public License as published by
!* the Free Software Foundation, either version 3 of the License, or (at
!* your option) any later version.
!*
!* FMScoupler is distributed in the hope that it will be useful, but WITHOUT
!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
!* for more details.
!*
!* You should have received a copy of the GNU Lesser General Public
!* License along with FMScoupler. If not, see <http://www.gnu.org/licenses/>.
!***********************************************************************

!> @file
!! @brief Example code
!! @author <developer>
!! @email [email protected]

module example_mod
use FMS, only r4_kind, r8_kind, i4_kind, i8_kind, util_func1
implicit none
private

public :: sub1
public :: func1
public :: ex_subroutine

interface ex_subroutine !< generic interface block. When the user
module procedure ex_subroutine_r4 !! calls ex_subroutine, the compiler checks
module procedure ex_subroutine_r8 !! the input arguments and invokes either
end interface ex_subroutine !! ex_subroutine_r4 or ex_subroutine_r8
!! ex_subroutine_r4/8 are generated by the preprocessor
!! which requires example_r4.fh, example_r8.fh, and
!! example.inc files

!> @brief Doxygen description of type.
type,public :: CustomType
private
integer(kind=i4_kind) :: a_var !< Inline doxygen description.
real(kind=r8_kind),dimension(:),allocatable :: b_arr !< long description
!! continued on
!! multiple lines.
endtype CustomType

contains

!> @brief Doxygen description.
subroutine sub1(arg1, arg2, &
& arg3)
real(kind=r4_kind),intent(in) :: arg1 !< Inline doxygen description.
integer(kind=i8_kind),intent(inout) :: arg2 !< Inline doxygen description.
character(len=*),intent(inout) :: arg3 !< Long inline doxygen
!! description.

arg1=2.456_r4_kind
end subroutine sub1

!> @brief Doxygen description
!! @return Function return value.
function func1(arg1, arg2) result(res)
integer(kind=i4_kind),intent(in) :: arg1 !< Inline doxygen description
integer(kind=i4_kind),intent(in) :: arg2 !< Inline doxygen description
integer(kind=r8_kind) :: res

res=real(arg1,r8_kind) * 3.14_r8_kind
end function func1

#include "example_r4.fh" !< These two header file contains the macro definition
#include "example_r8.fh" !! and an "#include example.inc" where the procedure
!! is defined. See below.
end module example_mod
```
```Fortran ./include/example_r4.fh file
!***********************************************************************
!* GNU Lesser General Public License
!*
!* This file is part of the GFDL Flexible Modeling System Coupler.
!*
!* FMScoupler is free software: you can redistribute it and/or modify it under
!* the terms of the GNU Lesser General Public License as published by
!* the Free Software Foundation, either version 3 of the License, or (at
!* your option) any later version.
!*
!* FMScoupler is distributed in the hope that it will be useful, but WITHOUT
!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
!* for more details.
!*
!* You should have received a copy of the GNU Lesser General Public
!* License along with FMScoupler. If not, see <http://www.gnu.org/licenses/>.
!***********************************************************************

!> @file
!! @brief Example _r4.fh file containing macro definitions
!! @author <developer>
!! @email [email protected]

#undef FMS_EX_KIND_
#define FMS_EX_KIND_ r4_kind

#undef EX_SUBROUTINE_
#define EX_SUBROUTINE_ ex_subroutine_r4

#include "example.inc" !< example.inc file contains the procedure definition
```
```Fortran ./include/example_r8.fh file
!***********************************************************************
!* GNU Lesser General Public License
!*
!* This file is part of the GFDL Flexible Modeling System Coupler.
!*
!* FMScoupler is free software: you can redistribute it and/or modify it under
!* the terms of the GNU Lesser General Public License as published by
!* the Free Software Foundation, either version 3 of the License, or (at
!* your option) any later version.
!*
!* FMScoupler is distributed in the hope that it will be useful, but WITHOUT
!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
!* for more details.
!*
!* You should have received a copy of the GNU Lesser General Public
!* License along with FMScoupler. If not, see <http://www.gnu.org/licenses/>.
!***********************************************************************

!> @file
!! @brief Example file _r8.fh file containing macro definitions
!! @author <developer>
!! @email [email protected]

#undef FMS_EX_KIND_
#define FMS_EX_KIND_ r8_kind

#undef EX_SUBROUTINE_
#define EX_SUBROUTINE_ ex_subroutine_r8

#include "example.inc" !< example.inc file contains the procedure definition
```
``` Fortran ./include/example.inc file
!***********************************************************************
!* GNU Lesser General Public License
!*
!* This file is part of the GFDL Flexible Modeling System Coupler.
!*
!* FMScoupler is free software: you can redistribute it and/or modify it under
!* the terms of the GNU Lesser General Public License as published by
!* the Free Software Foundation, either version 3 of the License, or (at
!* your option) any later version.
!*
!* FMScoupler is distributed in the hope that it will be useful, but WITHOUT
!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
!* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
!* for more details.
!*
!* You should have received a copy of the GNU Lesser General Public
!* License along with FMScoupler. If not, see <http://www.gnu.org/licenses/>.
!***********************************************************************
!> @file
!! @brief Example .inc file containing subroutine definitions/declarations
!! @author <developer>
!! @email [email protected]

!> The macro EX_SUBROUTINE_ gets replaced by the preprocessor
!! as ex_subroutine_r4 (as defined in the example_r4.fh file) and
!! as ex_subroutine r8 (as defined in the example_r8.fh file)

subroutine EX_SUBROUTINE_(arg1, arg2, arg3)
real(FMS_EX_KIND_), intent(in) :: arg2 !< FMS_EX_KIND_ gets replaced by the preprocessor
real(FMS_EX_KIND_), intent(out) :: arg1 !< FMS_EX_KIND_ gets replaced by the preprocessor
integer(i4_kind) :: arg3
integer, parameter :: lkind=FMS_EX_KIND_ !< kind parameter local to the subroutine

arg1 = arg2 / 4.0_lkind !< GCC does not like 4.0_FMS_EX_KIND_. Thus, the
!! parameter lkind is declared and used.

end subroutine EX_SUBROUTINE_
```

## C/C++

### General
* C code is written in GNU style. Each new level in a program block is indented
by 2 spaces. Braces start on a new line, and are also indented by 2 spaces.
* See the [Gnome C coding style guide](https://developer.gnome.org/programming-guidelines/stable/c-coding-style.html.en)
for more information
Loading
Loading