컨벤션 적용 기준¶

상태: 채택 · 기준일: 2026-09-15

현재 작성된 C++ 코딩 8개와 Git 2개, 총 10개 문서를 개인 개발의 기준으로 사용한다. 이 페이지는 적용 범위와 문서 위치를 안내하며 규칙 전문을 복제하지 않는다.

적용 문서¶

영역	기준 문서	다루는 내용
코딩	명명	식별자·상수 이름
코딩	초기화	초기값·생성자 선택·축소 변환
코딩	포맷	탭·괄호·공백·UTF-8·LF
코딩	const	읽기 전용 의도와 const 적용
코딩	주석	구현 설명·API 문서·작업 메모
코딩	헤더·include	헤더 독립성·직접 의존성
코딩	함수 매개변수·반환	입력·입출력·결과 전달
코딩	소유권·수명	소유·대여·스마트 포인터 전달
Git	커밋 메시지	형식·type·언어·호환성 변경
Git	브랜치 명명	작업 목적·이슈 번호·릴리스 이름

처음에는 포맷과 명명을 확인하고, 초기화·const·함수 규칙으로 이어서 읽는다. 헤더·주석·소유권은 파일 구성과 API 설계 시 함께 참고한다.

적용 방식¶

각 문서의 필수, 권장, 선택 강도를 그대로 유지한다. 채택이 모든 권장을 필수로 바꾸는 것은 아니다.
C++ 규칙은 신규 개인 C++ 코드에, Git 규칙은 개인 프로젝트의 새 커밋 메시지와 작업 브랜치 이름에 적용한다. 공통 기준은 위키의 채택 규칙이며, 기존 프로젝트도 변경하는 범위부터 맞춘다. 프로젝트 제약으로 달라지는 부분은 아래 절차에 따라 예외로 기록한다.
규칙이 여러 주제에 걸치면 상세 정의가 있는 문서를 따른다. 스마트 포인터 전달은 소유권 문서, const 여부는 const 문서, 이름은 명명 문서가 기준이다.
ref/는 과거 자료와 비교 근거다. 현재 규칙과 다르면 이 목록의 기준 문서를 따른다. 외부 가이드도 참고 근거이며 개인 규칙을 자동으로 대체하지 않는다.
예제의 최소 언어 버전과 프로젝트 표준 버전은 구분한다. C++11·14 기본 예제와 C++17·20·23 조건부 기능을 프로젝트 지원 범위에 맞게 사용한다.
문서의 후속·미결정 사항은 채택된 규칙으로 확정한 것으로 해석하지 않는다. 미지정 규칙은 아래 절차에 따라 프로젝트에서 구체화하고 위키에 반영한다.

위키와 프로젝트의 상호 반영¶

적용 범위는 이 위키를 사용하는 개인 프로젝트다. 공통 컨벤션의 기준은 항상 위키의 채택 규칙으로 둔다. 프로젝트에서 발견한 요구와 실제 적용 결과로 위키를 갱신하되, 프로젝트의 임시 선택과 공통 채택을 구분한다. 이 절차는 사용자가 선택한 운영 기준이다.

위키 확인 — 필수. 프로젝트 작업 전에 관련 문서의 현재 채택 상태와 적용 범위를 확인한다. 초안·보류·폐기·미결정 내용을 채택 규칙처럼 적용하지 않는다. 접근할 수 없으면 확인하지 못한 범위와 임시로 참고한 자료를 기록한다.
미지정 규칙 구체화 — 필수. 실제 구현에 필요한 선택을 프로젝트에서 정하고 적용 범위·이유·예외·필요한 예시를 기록한다. 사용자 선택이 없는 임시 결정은 시험 적용으로 표시한다. 기존 코드에서 반복된다는 사실만으로 공통 규칙을 자동 채택하지 않는다.
위키 반영 — 필수. 여러 프로젝트에 적용할 내용은 해당 공통 문서에, 특정 엔진·플랫폼에 한정된 컨벤션은 projects/의 해당 문서에 반영한다. 명확한 사용자 선택이나 기존 채택 근거가 있으면 그 범위에서 채택하고, 제안 단계이면 초안으로 남긴다. 미결정·보류·폐기도 구분하며 해당 문서와 이 페이지의 변경 기록을 갱신한다.
프로젝트 반영 상태 기록 — 필수. 프로젝트에는 위키 링크와 실제 적용 범위, 시험 적용·예외·미반영 사항을 남긴다. 공통 규칙 전문은 복제하지 않는다. 위키 개정으로 영향받는 코드와 요청 범위의 도구 설정을 확인하고 관련 작업 범위부터 맞춘다. 즉시 적용하기 어려우면 대상·이유·후속 반영 조건을 기록한다.
결과를 다시 위키에 반영 — 권장. 시험 적용에서 드러난 제약이나 예외를 관련 규칙에 반영한다. 임시 선택을 유지·수정·폐기한 이유를 남겨 다음 프로젝트에서도 판단 근거를 확인할 수 있게 한다.

기록 위치와 예외¶

공통 규칙의 상세 정의는 위키의 주제별 문서 한 곳에 둔다. 위키 안에서 특정 프로젝트의 핵심 요약·전용 규칙·제약·적용 상태는 docs/projects/에만 기록한다. 상세 환경·설계·실행 절차·검증 기록은 프로젝트 저장소로 연결하며 위키에 복제하지 않는다. 공통 문서는 일반화한 규칙과 필요한 근거 링크만 유지하며, README·목차·사이트 메뉴에서는 프로젝트 문서로 연결한다. 프로젝트별 컨벤션과 공통 기준의 예외는 위키의 프로젝트별 문서에서 관리하고, 실행 방법·구현 상태·설계 상세는 해당 프로젝트 문서를 원본으로 유지한다. 프로젝트 문서에서 예외를 안내할 때는 위키의 해당 항목을 링크한다. 작은 프로젝트는 별도 문서를 늘리지 않고 README에 적용 상태를 기록해도 된다.

프로젝트 제약이나 명시적 합의로 공통 기준과 달라질 때는 대상 규칙·적용 조건·이유·상태를 기록한다. 프로젝트의 기존 합의는 해당 범위의 예외로 관리하며 위키의 공통 기본값을 바꾸지 않는다. 위키에 아직 반영하지 못한 결정은 프로젝트에 임시 기록하고 후속 반영 대상으로 남긴다.

프로젝트 문서의 단일 파일·프로젝트별 폴더 구성과 분리 절차는 프로젝트 문서의 확장과 분리를 따른다.

마지막 확인·반영 시점¶

프로젝트에 위키의 확인일과 마지막으로 확인·반영한 커밋을 기록하는 것을 권장한다. 커밋 번호는 과거 규칙에 고정하기 위한 기준이 아니라 반영 상태를 추적하는 기록이다. 확인만 한 변경과 실제 코드에 반영한 변경은 구분한다. 미커밋 초안을 사용했다면 문서·변경 내용·시험 적용 대상을 기록한다.

예를 들어 프로젝트에서 처음 정한 오류 처리 방식은 우선 시험 적용으로 기록한다. 공통으로 사용할 수 있는 부분은 위키의 오류 처리 초안에, Win32 전용 처리는 프로젝트별 문서에 반영한다. 사용자가 공통안을 채택하면 위키의 상태를 갱신하고 프로젝트에 적용 결과를 기록한다.

위키 문서 편집과 커밋·푸시·배포는 별개다. 이 절차가 원격 반영이나 무관한 코드의 일괄 수정을 자동 승인하지 않는다.

다음 개정 범위¶

영역	남은 내용
명명	파일·네임스페이스·약어·매크로, 일반 구조체 정적 변수
포맷	switch·짧은 람다·복잡한 템플릿
C++	오류 처리의 통일 정책, mutable, 전달 템플릿
프로젝트별 규칙	설계·구성·빌드, 표준 버전·컴파일러, PCH·모듈, 자동 포맷·편집기 설정, COM·DX12·GPU 자원·ECS·메모리 풀
Git·협업	병합·리뷰·브랜치 수명, 자동 생성 메시지·릴리스·검증 도구
다른 분류	C, 테스트·품질, 일반 문서화

미작성 항목은 후속 대상으로 유지한다. 위 후속 항목과 도구 설정은 현재 채택 범위에 포함하지 않는다.

검토 중인 초안¶

문서	상태와 범위
RnimanEngine 프로젝트 기준	참조 초안. D3D12 초기 구현 선택과 프레임 동기화 전환은 사용자 결정에 따라 프로젝트 한정 채택하며 시험 적용과 구분
HLSL 셰이더 규칙	공통 초안. 명명·좌표 공간·단계별 파일·진입점·공유 include·산출물 구분
HTML 기본 컨벤션	공통 초안. 문서 골격·포맷·입력·접근성·JSX 차이
Material Forge 참고 기록	참조 초안. 로컬 원본·프로젝트 제약과 HTML 초안 미반영 상태
변경 검증과 결과 기록	공통 초안. 변경 범위와 빌드·실행·화면·성능 검증
원본과 생성물 관리	공통 초안. 재현 가능한 원본과 생성물의 구분

새 초안은 채택 문서 10개에 포함하지 않는다. 프로젝트에서 이미 적용한 선택도 공통 규칙의 자동 채택 근거로 사용하지 않는다. 초안의 필수·권장·선택은 채택 시의 제안 강도다.

변경 기록¶

2026-09-19: HTML 기본 컨벤션의 점진적 적용·포맷 자동화·브라우저 검증 기준을 보완하고 Material Forge 참고 기록에 후속 적용 순서를 기록했다. 공통 초안 상태를 유지하며 프로젝트 구현·도구 설정은 변경하지 않았다.
2026-09-19: Material Forge 소스·문서를 참고해 HTML 기본 컨벤션과 프로젝트 참고 기록을 작성했다. 새 스타일·개선 제안은 초안으로 유지하며 기존 채택 10개 문서의 규칙과 참고 프로젝트 코드는 변경하지 않았다.
2026-09-18: HLSL 셰이더 규칙을 사용자 제안에 따라 초안으로 작성하고 엔진 적용 상태를 연결했다. 기존 채택 10개 문서와 엔진 코드는 변경하지 않았다.
2026-09-18: RnimanEngine 삼각형 출력의 초기 셰이더·정점 자원 선택을 프로젝트 한정 시험 적용으로 기록했다. 공통 채택 규칙과 프로젝트의 기존 확정 선택은 변경하지 않았다.
2026-09-17: RnimanEngine의 프레임별 Allocator·Fence 값과 재사용 시 대기를 사용자 요청에 따라 프로젝트 한정 채택으로 기록했다. 리사이즈·종료 전체 대기와 검증 상태 구분을 유지하며 공통 채택 10개 문서는 변경하지 않았다.
2026-09-15: 사용자 선택으로 포맷의 120열 권장과 의미 구조 우선 배치를 채택했다. 인자·템플릿 타입 개수에 따른 줄바꿈 기준을 제거하고 관련 예제를 갱신했다. 프로젝트의 기존 120열 시험 적용 기록은 공통 채택 이후 상태와 구분했다.
2026-09-15: 포맷에 작업별 실패 처리와 인자 배치 예외를 구체화했다. 프로젝트의 120열 시험 적용은 공통 100열 권장과 구분한다.
2026-09-15: 프로젝트 문서에 사용자가 확정한 D3D12 초기 구현 선택과 시험 적용 상태를 반영했다. 공통 채택 10개 문서의 규칙은 변경하지 않았다.
2026-09-15: 프로젝트 문서의 범위를 핵심 요약·전용 컨벤션·주요 원본 링크로 제한했다. 원본 문서 구조를 복제하지 않고 전용 규칙이 늘어날 때만 분리하도록 구성 기준을 개정했다. 공통 초안의 상태는 유지했다.
2026-09-15: 사용자 선택에 따라 프로젝트 목차에 문서 확장·분리 기준을 채택했다. 단일 문서로 시작하고 필요할 때 프로젝트별 폴더와 주제별 문서로 전환하며 이동 시 링크·사이트 메뉴·빌드를 확인한다. 기존 파일 배치와 C++·Git 채택 문서 10개, 프로젝트별 초안 상태는 유지했다.
2026-09-15: 사용자 선택에 따라 위키 내 특정 프로젝트 정보는 docs/projects/에만 두도록 명시했다. 공통 문서의 실제 검증 사례·설정 설명을 프로젝트 문서로 모으고 일반 규칙과 근거 링크를 유지했다. 채택 문서 수와 나머지 초안 상태는 유지했다.
2026-09-15: 사용자 선택에 따라 위키 중심의 상호 반영 절차를 채택했다. project-records.md의 기준 관리 내용을 이 페이지에 통합하고 별도 초안은 삭제했다. 과거 커밋 고정 대신 위키의 채택 규칙을 기준으로 사용하며 프로젝트의 새 결정·시험 적용·예외를 위키로 반영한다. C++·Git 채택 문서 10개와 나머지 초안의 상태는 유지했다.
2026-09-15: 프로젝트 조사를 바탕으로 프로젝트 참조 문서와 공통 초안 3개를 추가했다. 재사용 가능한 기준을 추출하고 프로젝트별 설정·설계는 프로젝트 문서에 남겼다. 기존 채택 10개와 개인 스타일을 유지했으며 도구 설정·원격 프로젝트는 변경하지 않았다.
2026-09-14: 사용자 선택에 따라 미작성 분류인 설계와 프로젝트 구성·빌드를 프로젝트별 규칙으로 통합하고 전체 목차·사이트 탐색·관련 링크를 정리했다. 프로젝트에 따라 달라지는 결정을 한곳에서 다루며, 기존 채택 규칙 10개와 미결정 상태는 유지했다.
2026-09-12: 문서 분류를 정리하여 소유권·수명을 design/cpp-ownership.md에서 coding/cpp/ownership.md로 이동했다. 설계는 패턴·책임·의존성 구조, 프로젝트 구성·빌드는 폴더·타깃·개발 도구를 다루도록 목차의 범위를 명시했다. 기존 규칙과 채택 범위 10개는 유지했다.
2026-09-12: 사용자 요청으로 Git 커밋 메시지·브랜치 명명 규칙을 추가 채택하여 적용 범위를 총 10개 문서로 확장했다. 본문 문단 허용과 호환성 변경의 !·footer 병용도 포함했다.
2026-09-12: 작성된 8개 문서를 개인 기준으로 채택하고 혼재된 초안 상태를 정리했다.
사용자 선택인 탭 표시 4칸, UTF-8(BOM 없음)·LF, 마지막 인자 뒤 닫는 괄호, 선택적 지역 const, /// API 주석과 스마트 포인터 전달 규칙을 유지했다.
실제 폴더 이름에 맞춰 과거 자료 링크를 ref/로 통일했다.
2026-09-12 검토: 함수 괄호 배치에 생성자 초기화 목록·후행 지정자를 반영하고, 직접 include와 전방 선언의 적용 조건을 일치시켰다. 축소 변환 진단과 실행 중 범위 검사의 차이, 빌린 주소의 유효 조건을 명확히 했다.
같은 검토에서 정상값과 부재를 혼동하던 소유권 예제를 수정하고, 고정 상수와 실행 중 설정값의 명명을 구분했다. 중복 상태 표기와 검증 절의 규칙 반복을 줄였다. 기존 채택 스타일과 규칙 강도는 유지했다.

문서 경로는 유지하는 것을 기본으로 하며, 분류 개편으로 이동하면 관련 링크와 변경 기록을 함께 갱신한다. 규칙을 변경하면 해당 문서와 이 기록에 변경 범위와 이유를 남긴다. 이 페이지는 문서 기준이며 Git 태그·커밋·배포를 의미하지 않는다.