clang-format 설정

clang-format 설정은(는) 무엇을 하나요?

clang-format 코드 포매팅 도구를 즉시 사용 가능한 템플릿, 통합 스크립트, 포괄적인 참조 문서와 함께 구성합니다.

목적

이 스킬은 clang-format 설정 작업을 위한 절차적 워크플로우를 제공합니다:

• 검증된 템플릿에서 새로운 .clang-format 파일 생성
• 기존 코드 스타일을 분석하고 일치하는 설정 생성
• 번들 스크립트로 편집기 및 Git 통합 설정
• 참조 문서를 활용한 포매팅 동작 문제 해결

트리거 유형별 워크플로우 라우팅

호출되면, 어떤 트리거가 발생했는지에 따라 적절한 워크플로우로 라우팅합니다:

트리거 1: 명시적 clang-format 언급 → 사용자가 특정 옵션을 질문하면: references/01-09.md에서 관련 카테고리 참조 → 사용자가 전체 참조를 원하면: references/complete/clang-format-style-options.md로 안내 → 사용자가 CLI 사용법을 물으면: references/cli-usage.md 참조

트리거 2: 코드 스타일 분석 요청 → 아래 "기존 코드 스타일 분석" 워크플로우를 따릅니다 → 코드 샘플을 체계적으로 검사 (중괄호→들여쓰기→간격→줄바꿈→정렬) → 패턴을 assets/configs/에서 가장 가까운 템플릿에 매핑 → 초기 설정 가설을 임시 설정 파일 "/tmp/<repo_name>/hypothesis_.clang-format"로 생성 → 영향을 검증합니다: 대표 샘플 3-5개에 대해 clang-format --style="/tmp/<repo_name>/hypothesis_<number>.clang-format" file.cpp | diff - file.cpp 실행 → 가중치 점수를 사용하여 영향을 측정합니다: • 지표 1: 줄 수 변경 (추가/제거된 줄) - 가중치 10 • 지표 2: 줄 내 공백 변경 (기존 줄 내 간격) - 가중치 1 • 영향 점수 = (줄 수 변경 × 10) + (공백 변경 × 1) • 낮은 점수 = 리베이스 충돌, 향후 git-diff 분석, 병합 요청 변경 검토에 미치는 영향이 적음 = 더 나은 설정 → 반복합니다: 가장 영향이 큰 설정을 목표로 옵션 조정, 재테스트, 점수 비교 → 일관된 스타일 적용을 유지하면서 달성 가능한 최소 점수에 도달할 때까지 반복 → 사용자에게 보고합니다: 최종 설정을 다음 정보와 함께 제시 • 최종 영향 점수 및 세부 분석 (줄 변경 vs 공백 변경) • 테스트된 모든 가설과 점수를 보여주는 비교 표 • 무엇이 변경될지 보여주는 예시 diff 스니펫과 사용자가 직접 파일에 대해 테스트할 수 있는 명령어 • 선택된 설정에 대한 근거 → 설정을 확정하기 전에 사용자 승인을 기다립니다 → 승인 후에만 최종 설정 파일 제공

트리거 3: 설정 파일 작업 → 새로 생성하는 경우: 아래 "템플릿에서 새 설정 생성" 워크플로우를 따릅니다 → 기존 것을 수정하는 경우: 현재 설정을 읽고, 필요한 변경 사항을 식별하고, 관련 카테고리 가이드를 참조합니다 → 코드에서 생성하는 경우: 트리거 2 워크플로우(코드 스타일 분석)를 사용합니다

트리거 4: 포매팅 동작 조사 → 아래 "포매팅 문제 해결" 워크플로우를 따릅니다 → --dump-config로 설정 감지 확인 → 영향받는 카테고리를 식별하고, 관련 references/0X.md 가이드를 참조합니다 → 최소 설정으로 격리된 옵션 테스트

트리거 5: 스타일 옵션 문의 → 질문을 카테고리에 매핑: 중괄호→03, 들여쓰기→04, 간격→05, 정렬→01, 줄바꿈→02 → references/에서 특정 카테고리 가이드 참조 → 해당하는 경우 quick-reference.md의 예제 제공

트리거 6: 최소 변경 요청 → "기존 코드 스타일 분석" 워크플로우를 사용하여 현재 패턴 매칭 → 변경을 최소화하기 위해 가장 가까운 템플릿에서 시작 강조 → 프로젝트 전체 적용 전에 대표 샘플에서 테스트 → 보존된 패턴과 정규화된 패턴 문서화

번들 리소스

설정 템플릿 (assets/configs/)

일반적인 시나리오에 최적화된 7가지 즉시 사용 가능한 .clang-format 템플릿:

• google-cpp-modified.clang-format - Google C++ 스타일 (4칸 들여쓰기, 120열 제한)
• linux-kernel.clang-format - Linux 커널 코딩 표준 (탭, K&R 중괄호)
• microsoft-visual-studio.clang-format - Microsoft/Visual Studio 규칙
• modern-cpp17-20.clang-format - 현대적인 C++17/20 스타일
• compact-dense.clang-format - 공간 제약 환경을 위한 간결한 스타일
• readable-spacious.clang-format - 가독성을 우선시하는 넉넉한 스타일
• multi-language.clang-format - 다중 언어 설정 (C++, JavaScript, Java)

템플릿 사용 시기: 새 프로젝트 시작, 팀 표준 수립, 또는 포매팅 접근 방식 빠르게 테스트.

통합 스크립트 (assets/integrations/)

세 가지 편집기 및 Git 통합 스크립트:

• pre-commit - 스테이징된 파일 자동 포매팅을 위한 Git 훅 스크립트 (pre-commit 또는 prek 프레임워크와 호환)
• vimrc-clang-format.vim - 저장 시 포매팅을 위한 Vim 설정
• emacs-clang-format.el - clang-format 통합을 위한 Emacs 설정

통합 사용 시기: 개발 워크플로우에 자동 포매팅 설정.

참고: pre-commit 훅 스크립트는 pre-commit 프레임워크(Python)와 prek(Rust 대안) 모두에서 작동합니다. 두 프레임워크 모두 동일한 구문의 .pre-commit-config.yaml을 사용합니다.

참조 문서 (references/)

카테고리별로 구성된 상세 문서:

빠른 탐색:

• index.md - 개요 및 문서 허브
• quick-reference.md - 설명이 포함된 완전한 작업 설정
• cli-usage.md - 명령줄 사용법, 편집기 설정, CI/CD 통합

옵션 카테고리 (01-09.md):

1. 01-alignment.md - 선언, 할당, 연산자의 수직 정렬
2. 02-breaking.md - 줄 바꿈 및 자르기 규칙
3. 03-braces.md - 중괄호 배치 스타일 (K&R, Allman, GNU 등)
4. 04-indentation.md - 들여쓰기 규칙 및 특수 사례
5. 05-spacing.md - 연산자, 키워드 주변 공백 제어
6. 06-includes.md - 포함/가져오기 구성 및 정렬
7. 07-languages.md - C++, Java, JavaScript를 위한 언어별 옵션
8. 08-comments.md - 주석 포매팅 및 리플로우
9. 09-advanced.md - 패널티 시스템, 원시 문자열 포매팅, 실험적 기능

전체 참조 (complete/):

• clang-format-cli.md - 전체 명령줄 인터페이스 문서
• clang-format-style-options.md - 예제가 포함된 모든 194개 스타일 옵션

일반적인 워크플로우

템플릿에서 새 설정 생성

새로운 .clang-format 파일을 생성하려면:

1. 요구 사항 식별 (스타일 가이드, 팀 선호도, 언어)
2. assets/configs/에서 가장 가까운 템플릿 선택
3. 템플릿을 프로젝트 루트에 .clang-format으로 복사
4. 포매팅 테스트: clang-format --dry-run file.cpp
5. 필요에 따라 references/01-09.md를 사용하여 특정 옵션 사용자 정의
6. 변경 사항 확인: clang-format file.cpp | diff - file.cpp

예시:

# Google C++ 템플릿 복사
cp assets/configs/google-cpp-modified.clang-format /path/to/project/.clang-format

# 샘플 파일에서 테스트
clang-format --dry-run /path/to/project/src/main.cpp

# 만족하면 적용
clang-format -i /path/to/project/src/*.cpp

기존 코드 스타일 분석

기존 코드와 일치하는 설정을 생성하려면:

1. 코드 샘플에서 포매팅 패턴 검사
2. 주요 특성 식별:
   • 중괄호 배치 → references/03-braces.md 참조
   • 들여쓰기 (공백/탭, 너비) → references/04-indentation.md 참조
   • 간격 (연산자, 키워드) → references/05-spacing.md 참조
   • 줄 바꿈 (열 제한, 자르기) → references/02-breaking.md 참조
   • 정렬 패턴 → references/01-alignment.md 참조
3. 패턴을 references/quick-reference.md의 가장 가까운 기본 스타일에 매핑
4. assets/configs/에서 해당 템플릿으로 시작
5. 관찰된 패턴과 일치하도록 특정 옵션 재정의
6. 대표 코드 샘플에서 테스트
7. 포매팅이 기존 스타일과 일치할 때까지 반복

이 워크플로우는 기존 프로젝트에 clang-format을 도입할 때 공백만 변경되는 것을 최소화합니다.

편집기 통합 설정

편집기에서 저장 시 포매팅을 활성화하려면:

Vim:

1. assets/integrations/vimrc-clang-format.vim 내용을 .vimrc에 복사
2. Vim 다시 시작 또는 설정 소싱
3. C/C++/Java 파일을 저장하여 포매팅 트리거

Emacs:

1. assets/integrations/emacs-clang-format.el을 Emacs 설정에 복사
2. Emacs 다시 시작 또는 설정 평가
3. 지원되는 파일을 저장하여 포매팅 트리거

다른 편집기: VS Code, CLion 및 기타 편집기 설정 방법은 references/cli-usage.md를 참조하세요.

포매팅을 위한 Git 훅 설정

옵션 1: pre-commit/prek 프레임워크 사용 (권장):

.pre-commit-config.yaml에서 설정:

repos:
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v19.1.7
    hooks:
      - id: clang-format

그런 다음 설치: pre-commit install 또는 prek install

옵션 2: 수동 Git 훅:

1. assets/integrations/pre-commit을 .git/hooks/pre-commit으로 복사
2. 실행 가능하게 만들기: chmod +x .git/hooks/pre-commit
3. 변경 사항을 스테이징하고 커밋하여 테스트

훅은 스테이징된 파일만 포매팅하고, 스테이징되지 않은 변경 사항은 보존합니다.

포매팅 문제 해결

포매팅이 예상치 못한 결과를 생성할 때:

1. 설정 감지 확인: clang-format --dump-config file.cpp
2. references/cli-usage.md에서 명령 옵션 확인
3. 영향받는 포매팅 카테고리 식별 (중괄호, 간격, 줄바꿈 등)
4. references/01-09.md에서 관련 카테고리 가이드 참조
5. 격리된 옵션 테스트: 의심되는 옵션으로 최소 설정 생성
6. 포괄적인 옵션 세부 정보는 references/complete/clang-format-style-options.md 확인

CI/CD 포매팅 검사 설정

지속적 통합에서 포매팅을 적용하려면:

1. references/cli-usage.md의 CI 예제 검토
2. 파이프라인에 clang-format 검사 추가:

   # 파일 수정 없이 포매팅 확인
   clang-format --dry-run --Werror src/**/*.{cpp,h}
   

3. 포매팅 위반 시 빌드 실패하도록 설정
4. 기여자를 위한 포매팅 요구 사항 문서화

주요 개념

기본 스타일: 미리 정의된 설정 (LLVM, Google, Chromium, Mozilla, WebKit, Microsoft, GNU)이 시작점을 제공합니다. BasedOnStyle: Google로 설정한 다음 특정 옵션을 재정의합니다.

다중 언어 지원: 단일 파일에서 Language: 키를 사용하여 다른 언어를 별도로 설정합니다. assets/configs/multi-language.clang-format 예제를 참조하세요.

패널티 시스템: clang-format은 포매팅 대안 간에 선택하기 위해 패널티를 사용합니다. 패널티 값이 높을수록 특정 선택을 억제합니다. 자세한 내용은 references/09-advanced.md를 참조하세요.

점진적 개선: 요구 사항에 가장 가까운 템플릿으로 시작한 다음 점진적으로 사용자 정의합니다. 대표 코드 샘플에서 자주 테스트합니다.

설정 테스트

# 파일 수정 없이 변경 사항 미리보기
clang-format --dry-run file.cpp

# 제안된 변경 사항의 diff 표시
clang-format file.cpp | diff - file.cpp

# 파일에 포매팅 적용
clang-format -i file.cpp

# 전체 프로젝트 포매팅
find src include -name '*.cpp' -o -name '*.h' | xargs clang-format -i

# CI에서 포매팅 확인 (위반 시 실패)
clang-format --dry-run --Werror src/**/*.{cpp,h}

탐색 전략

대부분의 작업에 대해 다음 순서를 따르세요:

1. 템플릿으로 시작: assets/configs/에서 즉시 사용 가능한 설정 탐색
2. 빠른 참조: 설명이 포함된 완전한 설정을 위해 references/quick-reference.md 확인
3. 카테고리 가이드: 특정 옵션 카테고리는 references/01-09.md 참조
4. CLI 사용법: 명령줄 및 통합 세부 정보는 references/cli-usage.md 참조
5. 전체 참조: 완전한 옵션 문서는 references/complete/ 사용

코드를 분석하거나 문제를 해결할 때는 포매팅 측면(중괄호, 간격, 정렬 등)을 식별하고 references/의 관련 카테고리 가이드로 바로 이동하세요.