docs: make explanatory sections topic-specific

Author: GideokKim

README.md

@@ -49,6 +49,24 @@ repository/
 
 > **Note:** 번역 상태는 공식 원문 변경에 따라 계속 업데이트될 수 있습니다.
 
+## 🧪 번역 범위 검증
+
+이 저장소는 `scripts/upstream-topic-map.json`을 현재 번역 범위의 기준 목록으로 사용합니다. 이 파일은 공식 Google C++ Style Guide의 주요 제목과 하위 제목을 기록한 manifest입니다.
+
+새 원문 주제가 추가되거나 문서 구조가 바뀌면 다음을 함께 갱신하세요.
+
+1. `scripts/upstream-topic-map.json`
+2. 대응하는 번역 Markdown 파일
+3. `mkdocs.yml` navigation
+4. 각 페이지의 `이해하기 쉽게 설명하기` 섹션
+
+로컬 검증 명령:
+
+```bash
+python3 scripts/check_translation_coverage.py
+mkdocs build --strict
+```
+
 ## 📖 참고 자료
 
 - [Google C++ Style Guide (원문)](https://google.github.io/styleguide/cppguide.html)

google cpp style guide/access_control.md

@@ -8,6 +8,15 @@
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-접근 제어 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 기술적인 이유로 Google Test를 사용할 때 .cc 파일에 정의된 테스트 픽스처 클래스의 데이터 멤버를 보호할 수 있습니다.
+
+실제로 코드를 볼 때는 이는 필요한 경우 접근자(보통 const ) 형태의 쉬운 상용구를 사용하여 불변성에 대한 추론을 단순화합니다.
+
+점검할 때는 특히 다음을 확인하세요:
+
+- 테스트 픽스처 클래스가 .cc 파일 외부에서 정의된 경우(예: .h 파일) 데이터 멤버를 비공개로 만듭니다.
+- 클래스의 데이터 멤버가 상수가 아닌 한 비공개로 만듭니다.

google cpp style guide/aliases.md

@@ -67,6 +67,15 @@ using ::foo::Bar;
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-별칭 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 - API나 유지 관리 가능성에 대한 영향을 고려하지 않고 구현에만 사용하도록 의도된 공개 별칭을 만들고 싶은 유혹이 있을 수 있습니다.
+
+실제로 코드를 볼 때는 해당 영역이나 .cc 파일의 별칭은 구현 세부 정보(클라이언트 코드가 이를 참조할 수 없기 때문에)이며 이 규칙으로 제한되지 않습니다.
+
+점검할 때는 특히 다음을 확인하세요:
+
+- 이러한 별칭은 의도된 용도를 문서화하지 않으며 그 중 절반은 클라이언트 사용을 위한 것이 아닙니다.
+- 공개 별칭은 API 사용자의 이익을 위한 것이며 명확하게 문서화되어야 합니다.

google cpp style guide/architecture_portability.md

@@ -13,6 +13,15 @@
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-아키텍처 이식성 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 예: int64_t my_value{0x123456789}; uint64_t my_mask{uint64_t{3} << 48}; - 이식 가능한 부동 소수점 유형을 사용하십시오.
+
+실제로 코드를 볼 때는 - 메모리 주소를 정수로 작업해야 하는 경우 uint32_t s 또는 uint64_t s가 아닌 uintptr_t s에 저장하세요.
+
+점검할 때는 특히 다음을 확인하세요:
+
+- - 값을 인쇄할 때 printf 함수 계열 대신 absl::StrCat , absl::Substitute , absl::StrFormat 또는 std::ostream 과 같은 유형이 안전한 숫자 형식 지정 라이브러리를 사용하십시오.
+- - 구조화된 데이터를 프로세스 내부 또는 외부로 이동할 때 메모리 내 표현을 복사하는 대신 프로토콜 버퍼와 같은 직렬화 라이브러리를 사용하여 인코딩하십시오.

google cpp style guide/boolean_expressions.md

@@ -18,6 +18,15 @@ if (this_one_thing > this_other_thing &&
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-불리언 표현식 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 또한 and 및 compl과 같은 단어 연산자보다는 항상 && 및 ~와 같은 구두점 연산자를 사용해야 합니다.
+
+실제로 코드를 볼 때는 긴 불리언 표현식이 있는 경우 줄을 끊는 방법에 일관성을 유지하세요.
+
+점검할 때는 특히 다음을 확인하세요:
+
+- 이는 Google 코드에서 더 일반적이지만 줄 시작 부분에 모든 연산자를 래핑하는 것도 허용됩니다.
+- 적절하게 사용하면 가독성을 높이는 데 큰 도움이 될 수 있으므로 추가 괄호를 신중하게 삽입하세요.

google cpp style guide/braced_initializer_list_format.md

@@ -36,6 +36,14 @@ MyType m = {  // Here, you could also break before {.
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-중괄호 초기화 목록 형식 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 중괄호로 묶인 목록이 이름(예: 유형 또는 변수 이름) 뒤에 오는 경우, {}가 해당 이름을 가진 함수 호출의 괄호인 것처럼 형식을 지정합니다.
+
+실제로 코드를 볼 때는 그 자리에서 함수 호출의 형식을 지정하는 것과 똑같이 중괄호 초기화 목록의 형식을 지정합니다.
+
+점검할 때는 특히 다음을 확인하세요:
+
+- 이 선택이 독자에게 숨은 전제나 비용을 만들지 않는지 확인하세요.

google cpp style guide/casting.md

@@ -25,6 +25,15 @@ Dynamic_cast 사용에 대한 지침은 RTTI 섹션을 참조하세요.
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-캐스팅 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 - 클래스에서 해당 슈퍼클래스로 포인터를 명시적으로 업캐스트해야 하거나 슈퍼클래스에서 서브클래스로 포인터를 명시적으로 캐스팅해야 하는 경우 값 변환을 수행하는 C 스타일 캐스팅과 동일하게 static_cast를 사용합니다.
+
+실제로 코드를 볼 때는 현재 수행 중인 작업을 알고 있고 앨리어싱 문제를 이해하는 경우에만 이 방법을 사용하십시오.
+
+점검할 때는 특히 다음을 확인하세요:
+
+- - reinterpret_cast를 사용하여 포인터 유형과 정수 및 void*를 포함한 다른 포인터 유형 간의 안전하지 않은 변환을 수행합니다.
+- 변환으로 인해 정보가 손실될 수 있는 경우 코드가 컴파일되지 않으므로 이는 가장 안전한 접근 방식입니다.

google cpp style guide/choosing_names.md

@@ -55,6 +55,15 @@ class MyClass {
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-이름 선택하기 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 약어가 사용되는 경우 단일 "단어"로 대문자로 시작하는 것이 좋습니다(예: StartRPC() 대신 StartRpc() ).
+
+실제로 코드를 볼 때는 이름은 사용 가능한 코드와 멀리 떨어져 사용되더라도 설명적이어야 합니다.
+
+점검할 때는 특히 다음을 확인하세요:
+
+- 새로운 독자가 코드를 즉시 이해할 수 있도록 만드는 것이 훨씬 더 중요하므로 수평 공간을 절약하는 것에 대해 걱정하지 마세요.
+- 헤더에 선언된 자유 함수는 헤더의 라이브러리를 언급해야 하지만 지역 변수는 그 안에 어떤 함수가 있는지 설명해서는 안 됩니다.

google cpp style guide/class_format.md

@@ -40,6 +40,15 @@ class MyClass : public OtherClass {
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-클래스 형식 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 참고 사항: - 모든 기본 클래스 이름은 하위 클래스 이름과 같은 줄에 있어야 하며 80열 제한이 적용됩니다.
+
+실제로 코드를 볼 때는 - public: , protected: 및 private: 키워드는 한 칸 들여쓰기되어야 합니다.
+
+점검할 때는 특히 다음을 확인하세요:
+
+- - 공개 섹션이 먼저 오고, 보호 섹션이 그 뒤를 따르고, 마지막으로 비공개 섹션이 와야 합니다.
+- public , protected 및 private 순서의 섹션은 각각 한 칸씩 들여쓰기됩니다.

google cpp style guide/class_template_argument_deduction.md

@@ -37,6 +37,15 @@ CTAD의 사용은 유형 추론에 대한 일반 규칙을 따라야 합니다.
 
 ---
 
+---
+
 ## 이해하기 쉽게 설명하기
 
-클래스 템플릿 인자 추론 규칙을 적용할 때는 원문 규칙을 문자 그대로 외우기보다, 왜 이 선택이 독자에게 더 명확한지 살펴보면 쉽습니다. 코드 리뷰에서는 이 기능이 호출 지점에서 의도를 숨기지 않는지, 더 단순한 구조로 같은 목적을 달성할 수 없는지, 기존 코드와 섞였을 때 유지보수 비용이 커지지 않는지를 확인하세요.
+이 규칙의 핵심은 가능한 경우 컴파일러 경고를 통해 이를 시행해야 합니다.
+
+실제로 코드를 볼 때는 템플릿 관리자가 하나 이상의 명시적인 추론 가이드를 제공하여 CTAD 사용 지원을 선택하지 않은 한 주어진 템플릿과 함께 CTAD를 사용하지 마세요(std 네임스페이스의 모든 템플릿도 선택한 것으로 추정됩니다).
+
+점검할 때는 특히 다음을 확인하세요:
+
+- 클래스 템플릿 인수 공제(종종 "CTAD"로 축약됨)는 템플릿 이름을 지정하는 유형으로 변수가 선언되고 템플릿 인수 목록이 제공되지 않은 경우(빈 꺾쇠 괄호도 포함되지 않음) 발생합니다.
+- 왜냐하면 해당 생성자의 작성자는 생성자가 CTAD에 발생할 수 있는 문제를 알 수 있는 방법이 없었기 때문입니다(수정은 말할 것도 없고).