CONTRIBUTING.md

Guidelines for code development, structure, formating etc.

The CORSIKA Project very much welcomes contributions. Here we outlined how you can find the right place to contribute, and how to do that. Connect to https://gitlab.ikp.kit.edu and corsika-devel@lists.kit.edu (self-register at https://www.lists.kit.edu/sympa/subscribe/corsika-devel) to get in touch with the project. The CORSIKA Project decides on the GUIDELINES and can decide to change/improve them.

How to contribute

• We organize all development via Issues that may be feature requests, ideas, discussions, or bugs fix requests.
• New issues can be created, or existing issues picked up or contributed to.
• Issues are discussed in meetings or via corsika-devel@lists.kit.edu
  within the CORSIKA Project.
• Issues are assigned to milestones.
• The work on issues is performed in branches that can be best created directly via the gitlab web interface.
• Proposed code to close one issue (located in a specific git branch) is reviewed, discussed, and eventually merged into the master branch to close the issue.

Code formatting

We rely on clang-format for code formatting. This has the tremendous advantage that definitely all code follows the same formatting rules, and nobody at any point needs to invest time and effort into code formatting. We provide a script do-clang-format.sh, which can be very useful. But we urge everybody to integrate clang-format already on the level of your source code editor. See the official page for information about clang-format and its editor integration. At least: run do-clang-format.sh prior to any git add command. Code with improper formatting will not be accepted for merging.

The definition of source code format is written down in the file .clang-format and can be changed, if the CORSIKA Project agrees on it. To see what is possible, check e.g. link1 or link2.

Naming conventions

While clang-format does the structural formatting, we still need to agree on naming conventions:

• Classes and structs start with capital letters

• Class member variables start with "f"

• Any static variable has a "g" prefix. A static member variable starts with "fg"

• Class member functions start with capital letters

• Any class getter begins with "Get", and setter with "Set". Logical getters start with "Is" or "Has".

• enums should be "enum class" and start with a capital "E"

• Function parameter names start with "v"

• We use namespaces to avoid clashes and to structure code

  • Everything is part of the corsika namespace
  • All classes and objects are encapsulated into suited sub-namespaces, thus corsika::geometry, corsika::processes, corsika::units, etc.
  • Namespace names do not use capital letters.
  • Every header file is copied during build and install into "include/corsika/[namespace]" which also means, each header file can only provide definitions for a single namespace. It is one main purpose of namespaces to structure the location of header files.
  • Each header file uses an include protection that includes at least the namespace name, and header file name, thus, #ifndef __include_geometry_Point_h__ or #ifndef __geometry_Point_h__, or similar are acceptable.
  • Header files should always be included with <..>, thus, #include <corsika/geometry/Point.h> since the build system will always provide the correct include directives (and files anyway cannot be found in file-system paths, which generally do not follow the namespace naming conventions outlined here).

• Header files are named after the main class (or object) they define. This also means each header file name starts with a capital letter.