Coding Conventions and IDEs

Table of Contents

• Repository organisation
• Configuring Peano in Eclipse
• Python Conventions / Style Guide
• C++ conventions / Style Guide
  • FAQs
• Python
  • FAQs
• Code Formatting

The page below enlists some recommendations on how to use particular IDEs, and it also provides coding and formatting guidelines.

The documentation guidlines however are hosted on a separate page.

Repository organisation

Peano's core is a collection of static libraries. A Peano application consists of C++ glue code which combines all of these libraries. This glue code is generated through the Python API.

• documentation Hosts the sources of the document that you hold in your hands. large-scale Peano applications.
• src Holds the C++ Peano sources of the Peano core and all the toolboxes.
• src/.../api Holds the Python API scripts of the underlying C++ code part.
• tests Collection of small test cases that can be automised.
• benchmarks Collection of benchmark scripts.
• tutorials Holds all the tutorials.
• applications Proper, real-world applications, i.e. bigger pieces of code built on top of Peano or one of its extensions. Often, these features are used in return by benchmarks and tutorials.

Configuring Peano in Eclipse

You can integrate Peano straightforwardly into Eclipse. Clone the repository locally and invoke

libtoolize; aclocal;
autoconf; autoheader;
cp src/config.h.in .;
automake --add-missing

Open the Eclipse GUI and run the following steps:

• Select New Project.
• Select a C++ project. Older Eclipse versions want you to pick the mode Managed Build. Some wizard generations distinguish C from C/C++. I always pick the C/C++ version.
• Locate the project at a remote directory (where you git deposits the clones).
• Select GNU Autotools. The Empty Project is the right one to select.
• You need only one target configuration. By default, Eclipse offers you to build Build and Debug. Disable the debug variant.

Some Eclipse wizards tend to overwrite Peano's configure.ac file. If this is the case, replace the files through

git restore  configure.ac
git restore  Makefile.am
git restore  src/Makefile.am

and clean the project in Eclipse. Once you've done so, I recommend that you give the .gitignore file some special treatment:

git rm --cached file

Eclipse tends to insert the documentation folder to the ignored files once you enable the autotools pipeline. Every new commit now will add this ignore entry to the global repo, which is something we don't want to have.

Python Conventions / Style Guide

Most users will interact with Peano through the Python API, which acts as glue to stick together various C++ snippets in a way that can be modified for each experiment.

We aim for our Python to look something like the PEP-8 style guide for Python. In particular, methods should be named all in lowercase, with words separated by underscores, such as:

def my_method_for_calulcating_residuals(*args):
  # code goes here

Moreover, class names should be in camel case:

class MyClassForStoringData:
  # code goes here

Python routines are documented with Doxygen docstrings, i.e. docstrings whose opening triple quotes are followed by an exclamation mark (see the example below). Every parameter description starts with a @param statement, followed by the parameter's name, a colon and its type. The description itself follows on the subsequent, indented lines:

def translate(graph, identifier):
  """!
 
  Translate a task graph into a sequence of mesh traversals
 
  @param graph: peano4.api.taskgraph.Graph
    The task graph to compile.
 
  @param identifier: str
    Prefix of every generated observer's name.
 
  """

Please do not write graph: peano4.api.taskgraph.Graph without the @param: Doxygen then does not recognise the parameter description.

Cross-references to other parts of the code are written with @ref, never with @see, and use the fully qualified name of the target, so Doxygen can resolve them into links:

Such tasks are never fused
(@ref peano4.api.taskgraph.compiler.FuseSteps._have_conflicting_data()).

Short names such as _have_conflicting_data() or translate() typically can not be resolved and yield a Doxygen warning.

More info can be found in the FAQs below.

C++ conventions / Style Guide

We mainly follow Oracle Java naming conventions in Peano, which we translate one-to-one into the C++ world. C++-specific principles are:

• At most 80 characters per line.
• One file per class.
• No tabs, but two spaces.
• Each class is represented by one header and one implementation file: We follow the convention that the header files only hold the declarations, while the cpp files hold the actual implementations. We kind of gave up on this convention in few particular places for speed, i.e. whenever a compiler should do inlining, i.e. remove function calls, but doesn't. If we found such places and suffered significantly in terms of performance, then we moved the implementation into the headers. These cases however have to be documented explicitly!
• The header files have the extension .h and the implementation have the extension .cpp
• Templates are also split into declaration (in header) and implementation. The implementation file is included by the header, as templates have to be all in header, and their extension is .cpph.
• Long, self-explaining names (no acronyms)
• One subdirectory per namespace

The documentation guidlines are hosted on a separate page.

If in doubt, you can use the automatic formatting tool described below, but it is crucial that you only format files which you had modified already, i.e. no formatting random files in the repo.

FAQs

• Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.
• Class names should normally use the CapWords (CamelCase) convention.
• Function names should be lowercase, with words separated by underscores as necessary to improve readability.
• Variable names follow the same convention as function names.

Python

Please try and follow the PEP 8 Style guide.

FAQs

• Modules should have short, all-lowercase names. Underscores can be used in the module name if it improves readability. Python packages should also have short, all-lowercase names, although the use of underscores is discouraged.
• Class names should normally use the CapWords (CamelCase) convention.
• Function names should be lowercase, with words separated by underscores as necessary to improve readability.
• Variable names follow the same convention as function names.

Code Formatting

Recently (2023) a code formatting script has been added to incrementally add consistent formatting throughout the project. Under the hood, it uses clang-format for C++ code, and black for Python code.

Since the idea is to incrementally add consistent formatting throughout, the code script is set up to only format files that have been modified on your local branch to the main branch, p4. Ideally, the formatting script should be run on your local branch before you submit a merge request.

The usage is straightforward. The script can be found in Peano/format.py. To format all files that differ from files on the main p4 branch, simply run

python3 format.py

If you want to compare your local branch to a different branch than p4, you can specify that using the -b or --branch flag, e.g.

python3 format.py --branch branch-I-want-to-merge-into

Note that the format script detects potential files which might need formatting using git, therefore only files tracked by the git versioning will be considered.

If you prefer to run the formatting script on individual files only, you can specify them using the --files flag:

python3 format.py --files myfile1.py myCppFile.cpp myCppHeaderFile.h

The --files flag doesn't check whether the files you provide are traced by git, and will try to format any files you provide. This can be used for instance to run the formatter on generated files.

Our formatting scripts works only within a virtual environment. To create such an environment, follow the following steps:

sudo apt install python-venv
rm -rf .formatting_python_env
python3 -m venv .formatting_python_env
source .formatting_python_env/bin/activate

We install the Python environments, remove old formatting tools, create a new environment within the Peano directory and finally activate this environment. From hereon, future steps should only require the very last step.

As with other parts of the code, the FAQs and Troubleshooting might contain further helpful instructions.