@@ -8,17 +8,17 @@ Code should be formatted consistently. Code should be mechanically formatted.
This helps other readers jump into a code base without having to sort through various types of brace placement and indentation, it removes one level of noise.
## C/C++ Formatting ##
Formatting is done via clang-format. The canonical definition of the style is found in the advligorts source code in the .clang-format file.
Formatting is done via [clang-format](https://clang.llvm.org/docs/ClangFormat.html). The canonical definition of the style is found in the advligorts source code in the [.clang-format](https://git.ligo.org/cds/advligorts/-/raw/master/.clang-format) file.
Note: not all of the CDS code has been/can be reformatted at this time. Some code with complex #ifdefs will need to be checked after reformatting and will require better test suites.
_Note:_ This format definition comes out of work with LDAS in the framecpp & nds code bases, and is an effort to become more consistent across the LIGO lab.
## Python Formatting ##
Python code should be formatted according to PEP 8.
Python code should be formatted according to [PEP 8](https://www.python.org/dev/peps/pep-0008/).
## Go Formatting ##
Go code should be formatted according to go fmt.
Go code should be formatted according to [go fmt](https://go.dev/blog/gofmt).
_Note:_ Go prefers tabs to spaces. That is ok, that is the idiomatic way for this language.
...
...
@@ -36,7 +36,7 @@ Some notes:
# Build Systems #
# C/C++ use CMake by default
CMake is the current industry standard. This should be the preferred system to build C/C++ code. It provides the ability to build across Windows, OSX, Linux systems.
[CMake](https://cmake.org/) is the current industry standard. This should be the preferred system to build C/C++ code. It provides the ability to build across Windows, OSX, Linux systems.
Newer/Modern CMake idioms should be used. This is defined with target based operations instead of variable based declarations.
...
...
@@ -45,9 +45,10 @@ There are places such as building Linux kernel modules or the RT models that CMa
# Version Control #
Put code in version control.
Prefer git and hosting on git.ligo.org.
Prefer git and hosting on [git.ligo.org](https://git.ligo.org).
For development use topic and issue branches.
Do not be afraid to commit WIP (work in progress) code to your branches. It is better to save items and make sure we have a history than to have things perfect.
Keep the master/head/main branch clean and working.
...
...
@@ -60,7 +61,7 @@ Reviews force us to write better code as we know that someone else will look at
By using a git workflow with merge requests we can formalize a review.
# Software Licensing #
The lab policy on software licensing is at https://dcc.ligo.org/M1500244/.
The lab policy on software licensing is at [M1500244](https://dcc.ligo.org/M1500244/).
# Packaging CDS Software #
...
...
@@ -128,7 +129,7 @@ Inputs must be converted to internal units before any other processing is done o
Conversions between two units should be handled by a single function or macro (allowing for overloading for different types). A- hoc conversions must be avoided.
In C++ “Strong” types can be used to represent types and prevent unintentional/incorrect conversion of types.
In C++ "Strong" types can be used to represent types and prevent unintentional/incorrect conversion of types.
# Architecture #
## Architect code to be tested ##
...
...
@@ -170,9 +171,9 @@ In Python functions can be extended to take clocks, sockets, … with default pa
CMake integrates testing via the ctest system. Any tests integrated here can be run with the build system.
### C/C++ Catch/Boost Test ###
Catch is a simple/lightweight unit testing framework. It is used in parts of the daqd and other software.
[Catch](https://github.com/catchorg/Catch2) is a simple/lightweight unit testing framework. It is used in parts of the daqd and other software.
Boost::Testing is used by LDASTools
[Boost::Test](https://www.boost.org/doc/libs/1_77_0/libs/test/doc/html/index.html) is used by LDASTools
### Python ###
Use the python testing framework
...
...
@@ -180,7 +181,7 @@ Use the python testing framework
### Go ###
Go has a build in test/benchmark (and soon fuzzing) framework. It should be used for unit tests.
In addition GoConvey is a useful tool/runner for reloading and running your tests as you save files.
In addition [GoConvey](https://github.com/smartystreets/goconvey) is a useful tool/runner for reloading and running your tests as you save files.
# API Design #
Design APIs to keep objects in known good states.
...
...
@@ -208,10 +209,10 @@ If we are creating a base library that will be consumed by outside applications
# Interfacing with multiple languages #
## SWIG ##
Swig is useful when interfacing C/C++ code with many different languages.
[Swig](https://www.swig.org/) is useful when interfacing C/C++ code with many different languages.
## PyBind11 ##
When a C++ library need only be exported to Python (and not to Java/Matlab/…) PyBind11 may be a better choice as it provides good integration and keeps the bindings in C++ (instead of the including another language [the SWIG system] into the mix).
When a C++ library need only be exported to Python (and not to Java/Matlab/…) [PyBind11](https://pybind11.readthedocs.io/en/stable/) may be a better choice as it provides good integration and keeps the bindings in C++ (instead of the including another language [the SWIG system] into the mix).
## ROOT ##
Some older applications use a C++ interpreter built into ROOT to expose C++ classes to Python. **Future use of ROOT is discouraged**.
