Style Guide

Introduction

This document defines the standard conventions used in code and documentation for this project to ensure consistency, readability, and maintainability.

General Formatting Rules

• Limit all lines to a maximum of 80 characters.
  Exception: Long headers after Doxygen's \section etc. may exceed 80 chars while Doxygen requires the whole header in that line.
• Use 2 spaces for indentation.
• Do not use tabs under any circumstances.
• Do not allow trailing whitespace at the end of any line.
  Exception: In Markdown two trailing whitespaces are required to start a new line.
• Text files should be ended with a newline.
• Always prefer Markdown for documentation.
  Especially:
  • Use two whitespaces instead of \n
  • Prefer _italics_ over <em>italics</em>.
  • Prefer __bold__ over <b>bold</b>.
  • Prefer - item for lists.
  • Remark: * can be misinterpreted as a list marker. Using _italics_, respectively __bold__ for font styles and - item for lists resolves this ambiguity. Therefore, avoid alternatives such as *italics*, **bold**, or * item.
• HTML and other markup formats may be used instead of Markdown. This can lead to inconsistencies.
  Examples:
  • Doxygen has certain non-Markdown commands such as \page, \warning
  • Some advanced functionality is only available in HTML

General Coding Conventions

• Use the prefix yac_ for exported symbols (yac_c for C, yac_f for Fortran).
  Example: yac_cinit()

C

• Use snake_case per default (for naming variables, functions...).
• (optional) Use CamelCase for names of types.
  Example: typedef struct struct_name MyStruct; MyStruct foo, bar;
• (recommended) Use curly braces also for one-line for, if, etc.
• Use const if possible.
• (optional) Follow east-const style for consistency.
  Examples:
  • int const foo not const int foo
  • int const * const foo not const int * const foo
• Each file should include all necessary header files. (Exception: For header-source file pairs, the source file does not need to include the header’s includes again). This simplifies dependency tracking.
• When a function or macro call does not fit on a single line, break after the opening parenthesis and indent the arguments. Pack as many arguments as fit within 80 characters per line rather than placing each argument on its own line.
  Example:
  

  CHECK_FIELD_COUPLE_IDX(
    couple, field_couple_idx, "routine_name");
   
  YAC_ASSERT_F(condition, "message %s %d", string_arg, int_arg);

• Larger modules are organized in subfolders. The folder contains a .h file named identical to the folder name to offer the public interface, arbitrarily many other files that should only be used inside the module, and an optional _internal.h file that provides an interface that is used inside the module but which should not be exposed to the outside.
  Example: refer to src/mci/couple_config

Fortran

• Use lowercase for keywords such as subroutine, implicit none, etc.
• Use allocatable arrays instead of automatic arrays were feasible in order to avoid issues with limited stack memory

Spelling Convention

• The name of the software YAC is always written in all caps. Depending on the context, exceptions are allowed (e.g. conflicting coding conventions)
• The name of the software yaxt is always written in lowercase. Depending on the context, exceptions are allowed (e.g. conflicting coding conventions)
• Use British English (BE) throughout general code and documentation.
• Use American English (AE) only for naming routines and symbols related to MPI, as MPI follows AE conventions.
• For other commonly used terms (e.g. software packages) the spelling used on the respective documentation should be used. Another good reference is wikipedia. Here is a list (in alphabetical order) of terms that are used frequently: netCDF, OASIS, ParaView, Python, SCRIP

Capitalization

• Titles of pages and sections etc. follow title case.