Bembel
Coding Guidelines

Development Principles

Contributions to the code base of Bembel need to follow the three development principles.

Isogeometric Multipatch
Surfaces 		Element-Wise
Assembly 		Clean Code
Policy
Bembel is a templated toolbox that offers functionality to solve boundary value problems with a boundary or finite element method on isogeometric multipatch surfaces. Due to technical advantages, the quadrature and assembly of the system matrices is performed element-wise. In a separate step conforming ansatz spaces are created. Further development of the code base should be consistent with the existing code style; code duplication should be avoided if possible.

Style Guide

In order to maintain high code quality, we have decided to follow the Google C++ Style Guide. In the following, we will list parts of the style guide that we consider particularly important.

Formatting

The external appearance of the code plays a major role in readability. As you should not think about formatting rules when programming or doing a code review, we use automation as much as possible. We check the code format with cpplint on every push.

Recommendation:

The formatting of the code can also be automated using useful helpers such as clang-format. Many text editors can use clang-format by default.

How do I format my code with clang-format?

Naming

During software development, more time is spent reading code than writing it. Therefore, names and descriptions should be chosen carefully in order to help other people reading your code, including your future self.

Recommendation:

Citing Kent Beck: "You need to convey the purpose, type, and lifetime of the variable to readers, you need to pick a name that’s easy to read, you need to pick a name that’s easy to write and format."

Where do I find naming rules?

Reuse Code

Helper Functions:

Put code which might be useful outside of your feature into the src/util folder. Name the file topic + "Helper". Everything needs to be placed in the util namespace.

Git Workflow

The public master branch represents the current state of the software and is the origin for any new feature development or bug fixes. Each developer pulls from the master, implements the feature or bug fix in Feature Branches and creates Pull Requests back into the master.

Feature Branches

Feature branches are the working space for developing new features and should always be branched of master. A successful feature implementation should comply with the following practices:

  1. Always branched from the last common state.
    • Otherwise, the master branch must be regularly merged into the feature branch.
  2. A feature is considered to be the smallest possible and traceable complete change to the code that does not break it.
  3. Every feature is added to the automated test suite before merged.

Where do I find more information about feature branches?

Git Commit Messages

Meaningful commitment messages, including pull request descriptions, are part of constructive communication for understanding your work. In doing so, commit messages should briefly but completely describe your changes to the code. The formulation should be chosen as if the commit makes the described changes to the code itself, so please do not use the past tense.
Commit messages need to fulfill the following rules:

  1. Limit the subject line to 50 characters
  2. Capitalize the subject line
  3. Do not end with a period "."
  4. Use the imperative mood in the subject line

If the 50 characters are not sufficient, this is a good indicator to split your commit into two separate commits. For pull requests, it can be helpful to add a text body that is separated from the title of the commit message by a blank line and describes all changes.

Why good commit messages matter?

Pull Requests

Contributions to the code base are tested automatically and reviewed by a developer. Each pull request need to follow the rules:

  1. The implementation is done according to the Google C++ Style Guide.
  2. Unit tests and example tests are build and run error free.
  3. A minimal Doxygen documentation is provided for the test and utilized classes.

If any of the above points are not fulfilled, the pull request may be rejected.