Style Guide

General C++ Style Guidelines

The Tiger HLM routing code is written in C++, utilizing some functions from native C libraries. As of now, it consists of approximately 1,400 lines of C++ code. The codebase follows a procedure-oriented programming (POP) structure, with the logic broken into many small, modular functions.

While the current program is relatively small, additional modules and functionality will be added over time. To ensure long-term maintainability, performance, and readability, the following guidelines must be followed when editing or extending the codebase:

---

Language and Compilation

• All code must conform to the C++17 standard.
• Code must compile cleanly using icpx without warnings or errors.

---

Code Structure and Formatting

• Use header (.hpp) files to declare function prototypes and structures.
• Function implementations must be placed in separate .cpp files.
• Keep functions small and focused. Each should perform a single, clearly defined task.
• The main.cpp should not need to be touched!

---

File Naming

• Use lowercase filenames.
• Separate words using underscores, not camelCase.
• Examples: build_info.cpp

---

Comments and Documentation

• All functions should be documented with brief, clear comments describing their purpose and inputs/outputs.
• Inline comments should explain non-obvious logic, but avoid restating what the code already says.
• There is no strict format for comments, but they must be easy to understand by future developers.
• It is recommended to use the GitHub Copilot extension in VSCode to assist with writing and documenting code.

---

Naming Conventions

• Use descriptive names for variables and functions.
• Avoid overly short or cryptic names unless they're standard (e.g., i, j for loop indices).
• Constants should use UPPER_CASE_WITH_UNDERSCORES.

---

Code Practices

• Avoid use of using namespace std; in header files. Prefer explicit std:: prefixes for clarity. Exception: using namespace boost::numeric::odeint is currently implemented but can be refactored later.
• Avoid global variables unless absolutely necessary.
• Prefer const and constexpr where applicable for clarity and safety.
• Favor standard containers (std::vector, std::map, etc.) over raw pointers unless performance dictates otherwise.
• Initialize all variables and avoid magic numbers.

---

Version Control

• All contributions should be made via pull requests with clear commit messages.
• Keep commits focused and logical — avoid lumping unrelated changes together.

---

Maintaining a clean and consistent style ensures that the Tiger HLM routing model can grow in complexity without becoming difficult to understand or modify. Even small contributions should aim to meet these standards.