# Coding and Documentation Guidelines for fmsolvr

These guidelines define the basic coding and documentation conventions for the *fmsolvr* project. 
Their goal is to keep the code base readable, maintainable, and reusable while supporting 
high‑performance numerical computing.

## 1. General Principles

Code should prioritize readability, correctness, maintainability, portability, and performance transparency.
Performance optimizations must not obscure the underlying algorithm. If non‑obvious constructs are required
for performance reasons, they must be explained with comments.

## 2. File Structure

Each header file should follow the same structure:

1. License header  
2. Include guard  
3. Includes  
4. Namespace declaration  
5. Declarations  
6. End of namespace  
7. End of include guard  

Example:

```cpp
#ifndef FMSOLVR_MODULE_FILE_HPP
#define FMSOLVR_MODULE_FILE_HPP

#include <...>

namespace fmsolvr {

// declarations

}

#endif
```

## 3. Namespaces

All library code must be placed inside:

```cpp
namespace fmsolvr
```

Submodules may use nested namespaces such as:

```
fmsolvr::math
fmsolvr::operator
fmsolvr::simd
```

Avoid introducing symbols into the global namespace.

## 4. File Naming

File names should be descriptive and use lowercase letters with underscores.

Examples:

```
rotation_coefficients.hpp
multipole_translation.hpp
buildinfo.hpp
```

## 5. Formatting

Use four spaces for indentation. Tabs should not be used.

The project may use clang-format where appropriate. Formatting may be disabled locally when necessary:

```cpp
// clang-format off
...
// clang-format on
```

## 6. Naming Conventions

Types use PascalCase.

```
RotationOperator
MultipoleExpansion
ParticleContainer
```

Functions use lowerCamelCase.

```
computeMultipoleExpansion()
applyRotation()
buildInteractionList()
```

Variables use lowerCamelCase.

```
particleCount
interactionLevel
rotationMatrix
```

Constants use UPPER_CASE.

```
MAX_EXPANSION_ORDER
DEFAULT_BLOCK_SIZE
```

## 7. Includes

Include only what is necessary. Prefer project headers before system headers.

Example:

```cpp
#include "fmsolvr/math/vector.hpp"
#include "fmsolvr/util/types.hpp"

#include <cmath>
#include <vector>
```

Avoid unnecessary transitive dependencies.

## 8. Comments

Comments should explain intent and algorithmic meaning rather than restating the code.
Important comments should describe algorithmic purpose, numerical assumptions, or performance considerations.

## 9. Documentation

Public classes and functions should include short documentation comments describing their purpose,
parameters, and behavior. Where possible, documentation comments should be compatible with Doxygen.

Example:

```cpp
/**
 * Computes the multipole expansion for a particle set.
 *
 * @param particles input particle container
 * @param order expansion order
 */
```

## 10. Tests

New algorithmic components should be accompanied by tests or benchmarks verifying correctness
and numerical stability. Test code must remain separate from library code.

## 11. Build System

All new components must integrate with the CMake build system.
Avoid hard‑coded paths and ensure portability across compilers.