Code Complete

Code Complete 정리 작업 가이드

이 문서는 이 저장소에서 Code Complete 각 장 요약 파일을 만들거나 수정할 때 따를 작업 기준을 정리한 문서다.

기본 원칙

• 1차 기준은 실제 책 PDF 내용임.
• 장 요약은 책의 전개 순서와 논지 흐름을 최대한 따라감.
• 설명은 “이 책은”, “저자는” 같은 메타 표현 없이 내용 자체만 서술함.
• 한국어 문장은 장황한 설명형보다 짧고 읽히는 메모형 문장을 우선함.
• 너무 압축해서 어색한 명사 조각만 남기지 않음.
• 짧더라도 문장으로 읽히는 수준은 유지함.

Markdown 형식

• 장 제목은 ##
• 절 제목은 ###
• 절 안의 하위 비유/주제는 ####
• PDF에 있는 장·절·소제목의 이름, 순서, 계층을 임의로 바꾸지 않음.
• 원문에 없는 소제목을 새로 만들거나, 서로 다른 소제목을 임의로 합치지 않음.
• 원문의 굵은 지침 문구는 소제목으로 승격하지 않고, 해당 소제목 아래의 - **지침** 형식으로 둠.
• 본문은 bullet list 중심으로 정리함.
• 사례를 넣을 때만 한 단계 안쪽으로 들여씀.
• 사례의 실제 예시를 더 쪼개면 한 단계 더 들여씀.
• 불필요한 중첩 bullet은 만들지 않음.
• 체크리스트는 전체를 >> blockquote로 감쌈.
• 체크리스트 제목, 중간 분류, bullet, 빈 줄까지 모두 줄 앞에 >>를 붙임.
• 체크리스트 내부 중간 분류는 >> **분류명** 형식으로 둠.

• 예:

  >> #### 체크리스트: 요구사항
  >> **구체적인 기능 요구사항**
  >> - 모든 입력이 명시되어 있는가?
  >>
  >> **요구사항 품질**
  >> - 각 요구사항은 테스트 가능한가?
  

본문 작성 톤

• 메모형 어미 사용
• 예: 시작, 라고 함, 제시, 가까움, 중요함, 이동됨
• 다만 이해 확장처럼 지나치게 잘린 표현은 피함.
• 자연스러우면 ~할 수 있음, ~이 아님, ~에 가까움 형태 허용

내용 압축 규칙

• 기존 bullet 수는 함부로 늘리거나 줄이지 않음.
• 먼저 기존 bullet 단위를 유지한 채 문장만 짧게 다듬음.
• 사례가 과하면 삭제 가능
• 사례는 기본적으로 최소화함
• 본문이 길어지면 사례 삭제를 우선 검토함
• 사례를 유지할 때는 본문 논지보다 한 단계 안쪽에 배치
• 장 전체가 길어지면 사례보다 핵심 논지를 우선 남김
• bullet은 가능하면 기존 개수를 유지하고, 함부로 잘게 분해하지 않음
• 문장은 짧게 줄이되, 명사 조각처럼 어색해지지 않게 유지함

원문 구조 판별 및 재작성 규칙

• PDF의 시각적 구조를 우선 확인함. 글자 크기와 굵기뿐 아니라 문장 길이, 앞뒤 공백, 줄바꿈, 들여쓰기, 페이지에서의 배치도 함께 보고 제목·소제목·본문·강조 지침을 구분함.
• 텍스트 추출본만 보고 구조가 불분명하면 PDF 해당 페이지를 직접 확인함.
• 번호가 붙은 절과 원문의 실제 소제목은 Markdown 제목으로 유지하고, 소제목 안에 굵게 표시된 지침은 굵은 bullet로 분리함.
• 사용자가 굵은 글씨만, 볼드체만을 요청하면 해당 범위의 원문 굵은 지침 문구만 추려서 넣고 임의의 설명을 덧붙이지 않음.
• 사용자가 똑같이를 요청하면 직전에 확정된 제목·굵은 지침·설명 범위와 형식을 다음 대상에도 동일하게 적용함.
• 사용자가 장이나 절을 처음부터 다시, 새로 작성하라고 하면 기존 내용을 보충하거나 부분 수정하지 않고 전체를 교체함.
• 전체 재작성에서는 기존 bullet 수 유지 규칙보다 PDF의 실제 구조와 논지 복원을 우선함.
• 예시는 원문상 대응하는 지침 아래에 두며, 예시 때문에 원문의 제목 계층을 변경하지 않음.

Chapter 31, 32에서 확정된 방향

• PDF 제목 구조를 그대로 유지함. 번호가 붙은 절, 실제 소제목, 소제목 안의 굵은 지침을 서로 다른 단계로 구분함.
• 소제목 아래에서는 원문이 굵게 강조한 지침을 빠짐없이 분리해 - **지침**으로 정리함.
• 원문에서 별도 굵은 지침으로 나뉜 항목은 문장이 비슷하더라도 한 bullet로 합치지 않음.
• 사용자가 예시를 요청한 절에는 각 지침과 직접 대응하는 짧은 예시를 배치함.
• 체크리스트, 추가 자료, 요점 정리는 원문의 순서와 분류를 유지함.
• 장 전체 재작성 요청에는 기존 요약을 기반으로 덧붙이지 않고 PDF에서 다시 확인해 새 원고를 작성함.

Chapter 2에서 확정된 방향

• 2.1, 2.2, 2.3 모두 같은 메모형 톤으로 통일
• modeling 같은 핵심 용어는 유지
• 2.1은 사례를 모두 제거하고 핵심 논지만 유지
• 2.2는 길 찾기 사례를 제거하고 핵심 개념만 유지
• 2.3은 비유별 구분은 유지하되 문장은 짧게 압축

Chapter 3에서 확정된 방향

• 원문 표는 장 요약 흐름에 필요한 경우 Markdown 표로 유지
• 체크리스트는 본문 요약과 시각적으로 구분되도록 전체를 >>로 감쌈
• 체크리스트는 원문 질문 형식을 유지하되 한국어로 자연스럽게 옮김

Chapter 4, 5에서 확정된 방향

• 본문은 “말하고자 하는 핵심 메시지” 중심으로 압축함
• 단, 핵심 메시지는 그것을 뒷받침하는 근거(이유·데이터)와 함께 한 문장으로 매끄럽게 제시함
  • 주장만 남긴 앙상한 명사 조각으로 줄이지 않음
  • 예: “고급 언어가 낫다”가 아니라 “고급 언어일수록 표현력이 높아 한 줄이 더 많은 일을 함”처럼 근거까지 담음
• 용어 사전식 나열은 제거함 (예: 4장의 언어별 설명, 5장의 설계 패턴 표)
  • 나열 자체가 핵심 논지가 아니면 빼고, 그것이 뒷받침하던 한 줄 논지만 남김
• 짧은 예시는 핵심을 보여주면 한 줄씩 적극적으로 붙임 (글만 있으면 허전하므로), 단 장황한 일화나 사전식 나열은 지양
  • 가능하면 원문에 나오는 예시를 그대로 씀 (예: “집” 추상화, sin() 결합, Tacoma Narrows 다리)
• 데이터·표는 흐름에 꼭 필요할 때만 유지함, 단순 데이터/사전식 표는 제거하고 한 줄 논지로 대체함
  • 제거한 표: 표 4-1(언어별 비율), 표 5-1(설계 패턴), 표 5-2(설계 형식성)
• 원문에서 비슷한 항목이 여러 ####로 흩어져 있으면, 한 묶음 아래 하위 bullet로 합침
  • 예: 5.1의 설계 7가지 본성은 #### 7개 대신 한 절 아래 bullet 7개로 정리
• minor 항목이 많을 때는 개별 설명 대신 이름만 한 bullet에 나열함
  • 예: 5.3의 “그 밖의 발견법” 11가지는 이름만 나열
• 관련 있는 항목이라도 억지로 한 묶음으로 합치지 않음, 원문처럼 개별 항목으로 두는 편이 더 읽힘 (추상화·캡슐화·정보 은닉을 묶었다가 오히려 헷갈려 되돌림)
• 구조 요소(체크리스트, 참고 자료, 요점 정리)는 유지하되 분량은 압축함
  • 참고 자료는 항목·구조는 보존하되 설명을 짧은 구로 줄이거나 한 줄에 묶음
  • 요점 정리는 기존대로 문장형을 유지함

참고 자료 / 요점 정리

• 참고 자료와 요점 정리는 항상 유지
• 이 두 부분은 장 요약의 필수 구성으로 간주
• 가능하면 책의 구조와 항목 수를 유지
• 표현은 한국어로 정리하되, 원문 의미와 배열은 최대한 보존
• 요점 정리는 본문처럼 메모형으로 과도하게 줄이지 않음
• 요점 정리는 Chapter 2의 요점 정리처럼 자연스러운 문장형 bullet을 유지함
• 본문은 메모형 요약, 요점 정리는 비교적 완결된 문장형 요약으로 구분함

작업 절차

• 먼저 PDF에서 해당 장과 절을 직접 확인
  • 원문 텍스트 추출은 프로젝트의 .tools/poppler/poppler-26.02.0/Library/bin/pdftotext.exe를 사용함.
  • 예: & .\.tools\poppler\poppler-26.02.0\Library\bin\pdftotext.exe -layout code-complete-2nd-edition-v413hav.pdf chapter.txt
  • 전체 추출본이 필요하면 .tools/code-complete.txt를 우선 확인하고, PDF와 차이가 의심되면 다시 추출함.
  • 추출한 텍스트는 임시 확인용으로 사용하고, 저장소에 남길 필요가 없으면 삭제함.
• 초안 작성 후 책 흐름과 항목 순서가 맞는지 점검
• 사용자 피드백이 생기면 문체, bullet 수, 사례 처리 방식을 이 문서에 반영
• 이후 장 작업 시 이 문서를 먼저 참고한 뒤 작성

This site is open source. Improve this page.