# FESA C++ Coding Style

## 목적

이 문서는 FESA production 및 test C++의 코드 스타일, 객체 설계, 문서화와 검증 규칙을
정의하는 project-local source of truth다. 새 C++를 작성하거나 기존 C++를 리팩터링하는
사람과 Implementation Agent는 작업 전에 이 문서를 읽어야 한다.

[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html)를 baseline으로
사용한다. 이 문서, `AGENTS.md`, 승인된 feature contract와 architecture/ADR이 Google guide의
일반 규칙보다 우선한다.

## 적용 범위와 우선순위

규칙 충돌 시 다음 순서로 해석한다.

1. 승인된 feature requirements, formulation, numerical-review, I/O와 reference contract
2. `AGENTS.md`, `docs/ARCHITECTURE.md`와 `docs/ADR.md`
3. 이 문서의 FESA-specific rule과 exception
4. Google C++ Style Guide
5. 기존 local style

새 코드는 이 문서를 즉시 준수한다. 기존 코드는 승인된 refactoring plan의 module slice
단위로 전환한다. 요청 범위 밖의 file을 style-only 이유로 함께 수정하지 않는다.

## Language와 Toolchain

- Production language는 C++17 이상이며 MSVC x64를 지원해야 한다.
- 승인된 build 기준은 CMake, Visual Studio generator와 Debug configuration이다.
- C++ compiler extension에 의존하지 않는다.
- MKL, TBB, HDF5와 Win32 type은 public solver core header에 노출하지 않는다.
- Standard library와 RAII를 manual lifetime management보다 우선한다.
- Google guide가 현재 권장하는 C++20 language target은 FESA의 C++17 contract를 바꾸지
  않는다.

## File 이름과 Header

- File 이름은 소문자 snake_case를 사용한다.
- Production 및 test source extension은 기존 FESA/CMake 관례인 `.cpp`를 유지한다.
- Header extension은 `.h`를 사용한다. 기존 `.hpp`는 승인된 migration slice에서 `.h`로
  바꾼다.
- Header는 self-contained여야 하며 include consumer의 transitive include에 의존하지
  않는다.
- Header는 `#pragma once` 대신 full repository path 기반 include guard를 사용한다.

예:

```cpp
#ifndef FESA_MATH_VECTOR3_H_
#define FESA_MATH_VECTOR3_H_

namespace fesa {

class Vector3 {};

}  // namespace fesa

#endif  // FESA_MATH_VECTOR3_H_
```

Include 순서는 다음과 같다.

1. 대응하는 header
2. C system header
3. C++ standard library header
4. Third-party header
5. FESA project header

각 non-empty group 사이에는 빈 줄을 두고 group 안에서는 알파벳순으로 정렬한다. 사용하는
symbol의 declaration을 제공하는 header를 직접 include한다.

## 이름 규칙

| 대상 | 규칙 | 예 |
| --- | --- | --- |
| class, struct, enum, alias | PascalCase | `ElementProperty`, `EntityIndex` |
| function, method, accessor | PascalCase | `ComputeStiffness()`, `NodeCount()` |
| local variable, parameter | snake_case | `element_index`, `source_order` |
| class data member | snake_case + trailing `_` | `youngs_modulus_` |
| struct data member | snake_case | `source_id` |
| compile-time/static constant | `kPascalCase` | `kNodeCount` |
| enumerator | `kPascalCase` | `FailureCategory::kModel` |
| namespace | snake_case | `fesa::hdf5_internal` |
| macro | UPPER_SNAKE_CASE | `FESA_MATH_VECTOR3_H_` |

Google guide는 accessor의 snake_case를 허용하지만 FESA는 사용자 승인에 따라 production
및 test 호출부를 포함한 모든 function name에 PascalCase를 적용한다. Constructor,
destructor와 operator 이름은 C++ language 규칙을 따른다.

이름은 물리 및 수치 의미를 드러내야 한다. `value`, `data`, `handler`, `manager`처럼 문맥이
없는 generic name을 넓은 scope에서 사용하지 않는다. Source label, internal entity index와
equation index를 이름에서 구분한다.

## Formatting

- `.clang-format`의 `BasedOnStyle: Google`을 사용한다.
- 들여쓰기는 space 2개이며 tab을 사용하지 않는다.
- 최대 line length는 80자다. Include, guard, URL과 분할할 수 없는 contract string은 Google
  guide의 예외를 따른다.
- Opening brace는 declaration/control statement의 마지막 줄에 둔다.
- Namespace body는 들여쓰지 않고 closing namespace comment를 작성한다.
- 한 statement에 한 declaration만 둔다.
- Variable은 가능한 가장 좁은 scope에서 선언과 동시에 초기화한다.
- `const`와 `constexpr`를 의미가 허용하는 범위에서 사용한다.
- `override`, `final`, `explicit`, `noexcept`와 `[[nodiscard]]`는 실제 contract를 표현할 때
  사용한다.

Formatting-only 변경과 behavior/architecture 변경은 같은 commit에 섞지 않는다.

## Class와 Interface 설계

- Class는 하나의 명확한 책임과 invariant를 가져야 한다.
- Polymorphic base는 public virtual destructor를 가져야 한다.
- Abstract interface에는 현재 concrete 구현이 공유하지 않는 future method를 추가하지
  않는다.
- 단독 ownership은 `std::unique_ptr`로 표현한다. 실제 shared lifetime이 없는
  `std::shared_ptr`는 사용하지 않는다.
- Non-owning pointer/reference의 lifetime은 Doxygen contract에 기록한다.
- Downcast와 type switch를 주요 확장 mechanism으로 사용하지 않는다.
- State가 없는 함수를 묶기 위한 static-only class를 만들지 않는다. Internal namespace와
  focused module을 사용한다.
- Base class에 optional field와 no-op method를 누적하지 않는다. Material density, plastic
  state와 anisotropic constitutive law처럼 독립적인 의미는 별도 capability 또는 구성
  객체로 설계한다.
- Public header가 implementation/vendor dependency를 역으로 끌어오지 않도록 한다.

Data-only record는 struct를 사용할 수 있다. Invariant, encapsulation, lifetime 또는 behavior가
있으면 class를 사용한다.

## FEM Module 책임

- `model`: immutable semantic definition과 stable source/internal identity
- `elements`: element numerical kernel, local contribution과 element recovery
- `properties`: element property identity와 concrete section data
- `materials`: constitutive capability와 concrete material behavior
- `fem`: DOF/equation numbering, scatter와 sparse pattern
- `assembly`: deterministic element/load contribution reduction
- `constraints`: constraint definition 적용과 equation policy
- `analysis`: procedure-specific lifecycle과 backend orchestration
- `results`: backend-neutral recovery record와 physical result identity
- `io`: Abaqus syntax/semantic mapping과 HDF5 schema implementation
- `math`: backend-neutral value/storage type와 private numerical adapter

한 module의 class가 다른 module의 owner 책임을 가져가지 않는다. Element가 global CSR을
직접 쓰거나 Node가 equation ID를 저장하거나 Material이 analysis state를 임의로 소유하면
안 된다.

## 중복과 공통화

같은 의미, units, coordinate, failure policy와 ownership을 가진 logic을 한 번만 구현한다.
현재 승인된 공통화 방향은 다음과 같다.

- 3D coordinate/axis/director 연산은 `Vector3` value class
- source label/set/instance 해석은 `SourceTargetResolver`
- full/free/constrained invariant는 `DofManager` owner validation
- MKL size/copy helper는 private dense-BLAS adapter
- ASCII case-insensitive comparison과 label parsing은 focused core utility

두 코드 block이 비슷해 보여도 formulation sign, result location, source identity 또는
tolerance가 다르면 공통화하지 않는다. 단 한 번 사용하는 logic을 future flexibility만을
위해 framework로 만들지 않는다.

## Error와 Ownership

- Expected failure는 `Status` 또는 `Result<T>`로 반환한다.
- Public solver API를 통해 backend exception이 그대로 새지 않게 한다.
- Unknown type/property/material 조합은 structured diagnostic으로 fail-closed 처리한다.
- Invalid input을 silent default, clamp, average 또는 fallback으로 숨기지 않는다.
- Candidate를 완성하고 검증한 뒤 Domain state, AnalysisState 또는 final HDF5에 commit한다.
- Stable ordering과 failure atomicity는 optimization option이 아니라 correctness contract다.

## Doxygen

Doxygen coverage는 production code에만 요구한다. Test function과 test helper에는 Doxygen를
요구하지 않는다.

Public/protected class와 function declaration은 다음 내용을 필요한 만큼 기록한다.

- `@brief`: 무엇을 하는지 동사형 한 문장
- `@param`: 이름만으로 드러나지 않는 units, coordinates, ownership 또는 valid range
- `@return`: success value와 failure 의미
- `@throws`: 실제로 경계를 넘어가는 exception
- `@pre`: caller가 보장해야 하는 invariant
- `@note`: deterministic order, lifetime 또는 backend constraint
- `@warning`: sign, physical/numerical distinction 또는 destructive side effect

예:

```cpp
/// @brief Computes the element stiffness in stable global DOF order.
/// @return A finite symmetric contribution or a structured model failure.
/// @note The returned matrix does not include nonphysical result terms.
virtual Result<Matrix> ComputeStiffness() const = 0;
```

Private/internal production function은 declaration 또는 definition에 목적을 기록한다. 수식,
sign, coordinate transform, lifetime, ordered reduction이나 failure preservation이
비자명하면 그 이유를 설명한다. Header declaration의 사용법을 `.cpp` definition에서 그대로
반복하지 않는다.

Comment는 코드 한 줄을 한국어 또는 영어로 번역하는 방식으로 작성하지 않는다. Public API
Doxygen는 일관된 tool output을 위해 영어를 기본으로 한다. Diagnostic message와 existing
contract language는 현재 외부 계약을 유지한다.

## Determinism과 수치 코드

- Element contribution은 stable source/internal index 순서로 생성한다.
- Parallel worker는 index-owned output만 수정한다.
- Floating-point reduction 순서는 명시적으로 고정한다.
- Refactoring 중 expression/reduction 순서를 편의상 바꾸지 않는다.
- Arbitrary `max(1, ...)`, zero clamp 또는 missing-row ignore를 추가하지 않는다.
- End action, section resultant, generalized result와 stress의 identity/sign을 구분한다.
- Reference mapping은 row order가 아니라 승인된 source identity와 component를 사용한다.

수치식을 공통화할 때는 현재 formulation과 test가 정의한 operation order 및 tolerance를
먼저 확인한다.

## Test와 변경 관리

- Production C++ 변경은 관련 C++ test와 같은 patch에 있어야 한다.
- Behavior 또는 interface 변경은 `RED -> observed failure -> minimal GREEN -> VERIFY`를
따른다.
- Refactoring test는 base interface 사용, ownership/lifetime, invalid combination,
  deterministic order와 current numerical result preservation을 검증한다.
- Focused test 뒤에 full MSVC x64 Debug build와 CTest를 실행한다.
- B33/MITC4 output 경계를 건드린 변경은 승인된 reference comparison을 다시 실행한다.
- Reference artifact, input path와 tolerance를 리팩터링에 맞춰 수정하지 않는다.
- Commit은 review 가능한 module slice로 제한하고 Conventional Commits를 사용한다.

## Tooling

Repository가 제공하는 설정을 우선한다.

```powershell
clang-format --dry-run --Werror <changed-cpp-and-header-files>
clang-tidy <changed-cpp-files> -- -std=c++17
doxygen Doxyfile
```

실제 build/test command는 `.harness/config.json`이 있으면 그 설정을 우선하고, 없으면
`AGENTS.md`와 Harness의 MSVC/CMake/CTest entry point를 따른다. 필요한 tool이 설치되지 않아
검증을 실행할 수 없으면 성공으로 간주하지 않고 environment limitation을 보고한다.

Generated Doxygen HTML과 tool cache/build output은 source control에 넣지 않는다.

## Implementation Agent Checklist

Implementation Agent는 C++ Step을 시작하기 전에 다음을 확인한다.

- 이 문서와 feature implementation plan을 읽었다.
- 변경할 base/concrete/module owner가 승인 설계와 일치한다.
- 관련 test file과 RED condition이 Step에 명시되어 있다.
- Public API naming과 production Doxygen가 이 문서에 맞는다.
- Vendor dependency와 ownership direction이 역전되지 않는다.
- Stable identity, numerical order, HDF5와 reference contract가 보존된다.
- Formatting, Doxygen, focused/full MSVC/CTest acceptance command가 계획되어 있다.