From f5e1f6fedd76a0ba1e30de97f98952c01a9ea3ca Mon Sep 17 00:00:00 2001
From: Peter Lemenkov <lemenkov@gmail.com>
Date: Tue, 10 Feb 2026 21:26:55 +0100
Subject: [PATCH] Add clang-format configuration and CONTRIBUTING.md

Add .clang-format with proposed code style for discussion:
- 4-space indentation (no tabs)
- Allman/BSD brace style
- 120 character line limit
- Pointer/reference aligned right (char *ptr)
- Includes not sorted (to avoid breaking builds)

Also add CONTRIBUTING.md with formatting instructions and editor
integration tips.

CI enforcement will be added after the team agrees on the style.

Signed-off-by: Peter Lemenkov <lemenkov@gmail.com>
Assisted-by: Claude (Anthropic) <https://claude.ai>
---
 .clang-format   | 85 +++++++++++++++++++++++++++++++++++++++++++++++++
 CONTRIBUTING.md | 59 ++++++++++++++++++++++++++++++++++
 2 files changed, 144 insertions(+)
 create mode 100644 .clang-format
 create mode 100644 CONTRIBUTING.md

diff --git a/.clang-format b/.clang-format
new file mode 100644
index 00000000..41219f0d
--- /dev/null
+++ b/.clang-format
@@ -0,0 +1,85 @@
+# SIPp clang-format configuration
+# Based on existing code style patterns in the repository
+
+Language: Cpp
+Standard: c++17
+
+# Base style - start from LLVM and customize
+BasedOnStyle: LLVM
+
+# Indentation
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+IndentCaseLabels: false
+IndentPPDirectives: None
+NamespaceIndentation: None
+
+# Braces - Allman/BSD style (braces on their own lines)
+BreakBeforeBraces: Allman
+# More granular control if needed:
+# BraceWrapping:
+#   AfterClass: true
+#   AfterControlStatement: Always
+#   AfterEnum: true
+#   AfterFunction: true
+#   AfterNamespace: true
+#   AfterStruct: true
+#   AfterUnion: true
+#   BeforeCatch: true
+#   BeforeElse: true
+#   IndentBraces: false
+
+# Line length
+ColumnLimit: 120
+
+# Pointer and reference alignment - attach to variable name
+PointerAlignment: Right
+ReferenceAlignment: Right
+# e.g., char *ptr, int &ref
+
+# Spacing
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+
+# Alignment
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Left
+AlignOperands: true
+AlignTrailingComments: true
+
+# Short statements
+AllowShortBlocksOnASingleLine: Empty
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+
+# Breaking
+BreakBeforeBinaryOperators: None
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializers: BeforeColon
+BreakStringLiterals: true
+
+# Arguments and parameters
+AllowAllArgumentsOnNextLine: true
+AllowAllParametersOfDeclarationOnNextLine: true
+BinPackArguments: true
+BinPackParameters: true
+
+# Includes
+IncludeBlocks: Preserve
+SortIncludes: false  # Don't reorder includes - can break builds
+
+# Other
+FixNamespaceComments: true
+MaxEmptyLinesToKeep: 2
+ReflowComments: false  # Don't reflow comments - can break formatting
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 00000000..c10b64eb
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,59 @@
+## Code Formatting
+
+This project uses [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to maintain consistent code style. Pull requests are automatically checked for formatting compliance.
+
+### Setup
+
+Install clang-format (version 18 recommended):
+
+```bash
+# Ubuntu/Debian
+sudo apt install clang-format-18
+
+# macOS
+brew install clang-format
+
+# Fedora
+sudo dnf install clang-tools-extra
+```
+
+### Usage
+
+Format a single file:
+
+```bash
+clang-format -i src/myfile.cpp
+```
+
+Format all source files:
+
+```bash
+find src include -type f \( -name '*.cpp' -o -name '*.hpp' -o -name '*.c' -o -name '*.h' \) | xargs clang-format -i
+```
+
+Check formatting without modifying files:
+
+```bash
+clang-format --dry-run --Werror src/myfile.cpp
+```
+
+### Editor Integration
+
+Most editors support automatic formatting on save:
+
+- **VS Code**: Install the "C/C++" extension, enable "Format On Save"
+- **CLion**: Built-in support, enable in Settings → Editor → Code Style
+- **Vim**: Use [vim-clang-format](https://github.com/rhysd/vim-clang-format)
+- **Emacs**: Use [clang-format.el](https://clang.llvm.org/docs/ClangFormat.html#emacs-integration)
+
+### Style Overview
+
+The project uses a style based on LLVM with these key settings:
+
+- 4-space indentation (no tabs)
+- Allman/BSD brace style (braces on their own lines)
+- 120 character line limit
+- Pointer/reference aligned right (`char *ptr`, not `char* ptr`)
+- Includes are not sorted (to avoid breaking builds)
+
+See `.clang-format` in the repository root for the complete configuration.