Skip to content

STYLE-GUIDE.md

Latest commit

 

History

History
68 lines (50 loc) · 4.24 KB

STYLE-GUIDE.md

File metadata and controls

68 lines (50 loc) · 4.24 KB
Raw

집필 스타일 가이드 (Spring Framework 한글 해설서)

이 문서는 각 모듈 챕터를 집필하는 모든 작성자(에이전트 포함)가 따르는 공통 규약이다. 목표: Spring Framework 7.1 소스 코드를 "책처럼 읽으며 공부"할 수 있는 한글 해설서.

1. 독자와 고도(추상화 수준)

  • 독자: Spring을 사용해봤지만 내부 구조/동작 원리를 코드 레벨로 이해하고 싶은 중급 개발자.
  • 고도: 아키텍처 + 핵심 흐름 중심.
    • 다룬다: 모듈의 책임, 패키지 구조, 핵심 인터페이스/클래스의 역할, 주요 동작 시나리오의 흐름, 설계 패턴, 확장 포인트, 핵심 메서드의 의미.
    • 생략한다: 모든 메서드의 시그니처 나열, 사소한 내부 유틸/예외 클래스, getter/setter, 단순 위임 메서드.
    • 원칙: "이 클래스가 왜 존재하고, 호출되면 무슨 일이 일어나는가"를 설명한다. 단순 API 레퍼런스가 되지 않는다.

2. 언어와 문체

  • 모든 본문은 한글. 단, 클래스/메서드/패키지 이름 등 식별자는 원문 영어 그대로 (BeanFactory, getBean()).
  • 설명형 문체. 친절하되 장황하지 않게. 한 문단은 3~5문장 이내.
  • 코드 인용 시 핵심 라인만 발췌하고, 그 위/아래에 한글 해설을 붙인다.

3. 다이어그램 = ASCII 아트

  • 모든 구조도/흐름도는 코드 펜스(```) 안의 ASCII 아트로 그린다. (Mermaid 사용 금지)
  • 자주 쓰는 형태:
    • 계층/구조도: 박스와 선으로 클래스 관계 표현.
    • 시퀀스/흐름도: 위→아래 또는 좌→우 화살표로 호출 순서 표현.
    • 상태/생명주기: 단계 박스를 화살표로 연결.
  • 예시:
   ┌──────────────────┐      getBean("foo")      ┌───────────────────┐
   │  Application       │ ───────────────────────▶ │  DefaultListable   │
   │  (호출자)          │                          │  BeanFactory       │
   └──────────────────┘                          └─────────┬─────────┘
                                                            │ doGetBean
                                                            ▼
                                                  ┌───────────────────┐
                                                  │  싱글톤 캐시 조회   │
                                                  └───────────────────┘

4. 챕터(모듈) 파일 구조

각 모듈은 <module>/ 디렉토리 하나를 가지며, 그 안에:

  • README.md — 모듈 표지. (1) 한 줄 정의 (2) 이 모듈이 푸는 문제 (3) 의존 모듈/의존받는 모듈 (4) 내부 목차(하위 챕터 링크) (5) 전체 패키지 구조 ASCII 맵.
  • NN-제목.md — 하위 챕터들. 번호 2자리 접두사로 읽는 순서를 고정. (예: 01-핵심-개념.md, 02-빈-생명주기.md)

하위 챕터 개수는 모듈 규모에 맞춘다 (작은 모듈 23개, 큰 모듈 58개).

5. 각 하위 챕터 권장 골격

  1. 무엇을/왜 — 이 챕터가 다루는 영역과 그게 필요한 이유.
  2. 핵심 타입 — 주요 인터페이스/클래스와 책임 (ASCII 구조도).
  3. 동작 흐름 — 대표 시나리오 1~2개를 단계별 + ASCII 흐름도로.
  4. 핵심 메서드 — 흐름에서 중요한 메서드 몇 개를 골라 "무슨 일을 하는지" 설명.
  5. 설계 포인트 / 확장점 — 적용된 패턴, 커스터마이징 훅.
  6. 정리 — 한 문단 요약.

6. 링크 규약

  • 모듈 간 참조는 상대 경로로: ../spring-beans/README.md.
  • 소스 위치를 짚을 때는 spring-core/src/main/java/...처럼 모듈 루트 기준 경로로 표기 (GitHub에서 클릭 가능하도록).

7. 정확성 원칙

  • 추측 금지. 반드시 실제 소스를 읽고 사실에 근거해 쓴다.
  • 버전은 Spring Framework 7.1.0-SNAPSHOT 기준.
  • 불확실하면 단정하지 말고 "~로 보인다" 대신 소스를 더 확인한다.