모국어로 적는 문서

영어가 아닌 모국어로 문서 · 주석을 적는 선택은 비영어권 개발 팀에서 자주 마주치는 결정. 이 글은 식별자 (영어) 와 문서 / 주석 (모국어) 의 분리 관습 · 유니코드 식별자 표준.

1. 두 종류의 텍스트

소프트웨어 코드는 두 종류의 텍스트:

식별자 (변수 · 함수 · 타입 · 파일 이름) — 컴파일러 · 언어 사양과 만나는 표면.
자연어 (주석 · 문서 · 로그 · 에러 메시지) — 사람만이 읽는 텍스트.

비영어권 팀에서 흔히 채택되는 분담:

식별자 — 영어. 외부 라이브러리 · 표준 API 와의 일관성, 도구 · 검색의 편의.
주석 · 문서 · 커밋 메시지 — 모국어. 팀 내부 의사소통의 정확도.
사용자 노출 텍스트 — 현지화 시스템 (i18n) 으로 분리.

이 분담이 절대적인 규칙은 아니지만, 일본 · 한국 · 중국 · 독일 · 프랑스 기업의 사내 코드베이스에서 사실상 표준에 가까운 패턴이라는 보고가 흔합니다.

2. 유니코드 식별자

대부분의 현대 언어는 식별자에 비 ASCII 문자를 허용:

Python — PEP 3131 (Python 3, 2007 채택) 으로 유니코드 식별자 허용. 표준 규칙은 UAX#31.
JavaScript / ECMAScript — ECMAScript 2015 (ES6) 부터 ID_Start / ID_Continue 기반 유니코드 식별자.
Java — 처음부터 유니코드 식별자 허용.
C# — 유니코드 식별자 허용 (@ 접두로 키워드 회피).
Rust — RFC 2457 (2018) 으로 비 ASCII 식별자 허용. 기본 옵트인.
Go — 유니코드 식별자 허용.

즉 한국어 / 한자 식별자는 다수 언어에서 문법적으로 가능. 그런데 실무에서 거의 채택되지 않는 이유:

외부 호환 — 표준 API · 라이브러리 · 문서 · 예시가 영어. 영어 식별자가 그것들과 자연스럽게 섞임.
도구 — IDE 자동완성 · 스택 트레이스 · 로그 파서 · grep 가 영어를 가정하는 경우가 많음.
타이핑 / IME — 식별자를 매번 IME 전환으로 입력하면 흐름이 끊김.
보안 — 동형이의 문자 (homoglyph) 공격. 라틴 a 와 키릴 а 가 시각적으로 같은 글자라 식별자 위장이 가능. 일부 언어 (Rust 등) 가 이에 대한 린트 경고.

이런 이유로 식별자는 영어, 자연어 텍스트는 모국어 라는 분담이 자주 권장됩니다.

3. 다른 길

전부 영어 — 글로벌 OSS 프로젝트나 다국적 팀의 표준 선택. 외부 기여자가 합류하기 쉽고 공개 시 마찰이 적음. 단점은 비영어 사용자의 의사소통 정확도가 떨어진다는 점. 미묘한 비즈니스 규칙을 영어로만 적으면 의도가 흐려질 수 있음.

전부 모국어 — 식별자까지 모국어로 통일. 사내 한정 · 교육용 코드에서 가끔. 외부 의존 (라이브러리 호출) 과 섞이는 시점에 일관성이 깨지므로 유지보수 부담이 커지는 경향.

영어 식별자 + 모국어 자연어 (혼합) — 가장 흔한 절충. 새 팀원이 외부 표준과 사내 맥락 둘 다에 빠르게 적응할 수 있다는 평.

선택은 팀 구성 · 고객 · 외부 노출 여부에 따라 달라집니다.

4. 한국어 문서의 실무

한국어로 적는 사내 문서 · 주석에는 다음이 자주 권장:

반각 / 전각 구분 — 코드 블록 · 식별자는 반각만, 본문은 일반 한글.
외래어 표기 — 라이브러리 / 제품 이름은 원문 (PostgreSQL · React) 을 유지. 음차 표기와 원문 표기가 섞이면 검색이 어려움.
기술 용어 — 정착된 한국어 번역 ("비동기" · "동시성") 은 한국어로, 정착 안 된 용어는 원문 ("memoization") 을 유지하거나 양쪽을 한 번 병기.
줄바꿈 / 구두점 — 한 문장 한 줄 (또는 한 문단 한 줄) 이 git diff 가독성에 유리.

5. 자주 쓰는 모양

# 사용자 토큰을 검증하고 만료 시 새 토큰을 발급한다.
# 만료 임계는 환경변수 TOKEN_TTL 로 제어.
def verify_and_refresh(token: str) -> Token:
    decoded = decode(token)
    if decoded.expires_at - now() < REFRESH_THRESHOLD:
        return issue_new(decoded.user_id)
    return decoded

i18n 으로 분리한 사용자 텍스트:

// messages/ko.json
{ "login.fail": "로그인에 실패했습니다." }
// messages/en.json
{ "login.fail": "Login failed." }

6. 자주 걸리는 자리

식별자에 한글을 쓴 라이브러리를 외부에 공개하면 영어권 사용자가 사용하기 어려움 — 공개 OSS 와 사내 코드의 정책을 분리.

동형이의 문자 사고 — 라틴 a 와 키릴 а 가 식별자에 섞여 들어가면 잡기 힘든 버그. 린터 · 컴파일러 경고를 켜 둠.

한글 파일명이 OS 별로 정규화 형식이 다름 — macOS 는 NFD (자모 분해) 형식, Windows / Linux 는 NFC (완성형) 가 흔함. git 저장소에 한글 파일명을 두면 이 차이로 충돌이 발생할 수 있음. 영문 파일명을 권장하는 흐름이 굳어진 이유 중 하나.

모국어 주석을 너무 길게 적으면 읽지 않음 — 같은 정보를 코드 자체로 표현 (이름 · 구조) 하는 편이 우선, 주석은 "왜 이렇게 했는지" 에 집중.

하고픈 말

비영어권 팀의 가장 자연스러운 분담은 식별자 영어 + 자연어 모국어 + 사용자 텍스트 i18n. 이 셋이 균형을 이룰 때 외부 표준의 일관성과 내부 의사소통의 정확도를 동시에 잡을 수 있습니다. 한국어 식별자는 문법적으론 가능해도 도구 · IME · 동형이의 문자의 비용이 큰 자리.

no-ai-credit
feature-flag-skeptic

PEP 3131 Supporting Non-ASCII Identifiers · Unicode UAX #31 Identifier and Pattern Syntax · ECMAScript Identifier Names and Identifiers · Rust RFC 2457 Non-ASCII identifiers · Unicode Security Considerations (UTS #39) · 국립국어원 · The Twelve-Factor App 을 참고합니다.

모국어로 적는 문서

1. 두 종류의 텍스트

소프트웨어 코드는 두 종류의 텍스트:

식별자 (변수 · 함수 · 타입 · 파일 이름) — 컴파일러 · 언어 사양과 만나는 표면.
자연어 (주석 · 문서 · 로그 · 에러 메시지) — 사람만이 읽는 텍스트.

비영어권 팀에서 흔히 채택되는 분담:

식별자 — 영어. 외부 라이브러리 · 표준 API 와의 일관성, 도구 · 검색의 편의.
주석 · 문서 · 커밋 메시지 — 모국어. 팀 내부 의사소통의 정확도.
사용자 노출 텍스트 — 현지화 시스템 (i18n) 으로 분리.

2. 유니코드 식별자

대부분의 현대 언어는 식별자에 비 ASCII 문자를 허용:

Python — PEP 3131 (Python 3, 2007 채택) 으로 유니코드 식별자 허용. 표준 규칙은 UAX#31.
JavaScript / ECMAScript — ECMAScript 2015 (ES6) 부터 ID_Start / ID_Continue 기반 유니코드 식별자.
Java — 처음부터 유니코드 식별자 허용.
C# — 유니코드 식별자 허용 (@ 접두로 키워드 회피).
Rust — RFC 2457 (2018) 으로 비 ASCII 식별자 허용. 기본 옵트인.
Go — 유니코드 식별자 허용.

즉 한국어 / 한자 식별자는 다수 언어에서 문법적으로 가능. 그런데 실무에서 거의 채택되지 않는 이유:

외부 호환 — 표준 API · 라이브러리 · 문서 · 예시가 영어. 영어 식별자가 그것들과 자연스럽게 섞임.
도구 — IDE 자동완성 · 스택 트레이스 · 로그 파서 · grep 가 영어를 가정하는 경우가 많음.
타이핑 / IME — 식별자를 매번 IME 전환으로 입력하면 흐름이 끊김.
보안 — 동형이의 문자 (homoglyph) 공격. 라틴 a 와 키릴 а 가 시각적으로 같은 글자라 식별자 위장이 가능. 일부 언어 (Rust 등) 가 이에 대한 린트 경고.

이런 이유로 식별자는 영어, 자연어 텍스트는 모국어 라는 분담이 자주 권장됩니다.

3. 다른 길

영어 식별자 + 모국어 자연어 (혼합) — 가장 흔한 절충. 새 팀원이 외부 표준과 사내 맥락 둘 다에 빠르게 적응할 수 있다는 평.

선택은 팀 구성 · 고객 · 외부 노출 여부에 따라 달라집니다.

4. 한국어 문서의 실무

한국어로 적는 사내 문서 · 주석에는 다음이 자주 권장:

반각 / 전각 구분 — 코드 블록 · 식별자는 반각만, 본문은 일반 한글.
외래어 표기 — 라이브러리 / 제품 이름은 원문 (PostgreSQL · React) 을 유지. 음차 표기와 원문 표기가 섞이면 검색이 어려움.
기술 용어 — 정착된 한국어 번역 ("비동기" · "동시성") 은 한국어로, 정착 안 된 용어는 원문 ("memoization") 을 유지하거나 양쪽을 한 번 병기.
줄바꿈 / 구두점 — 한 문장 한 줄 (또는 한 문단 한 줄) 이 git diff 가독성에 유리.

5. 자주 쓰는 모양

# 사용자 토큰을 검증하고 만료 시 새 토큰을 발급한다.
# 만료 임계는 환경변수 TOKEN_TTL 로 제어.
def verify_and_refresh(token: str) -> Token:
    decoded = decode(token)
    if decoded.expires_at - now() < REFRESH_THRESHOLD:
        return issue_new(decoded.user_id)
    return decoded

i18n 으로 분리한 사용자 텍스트:

// messages/ko.json
{ "login.fail": "로그인에 실패했습니다." }
// messages/en.json
{ "login.fail": "Login failed." }

6. 자주 걸리는 자리

식별자에 한글을 쓴 라이브러리를 외부에 공개하면 영어권 사용자가 사용하기 어려움 — 공개 OSS 와 사내 코드의 정책을 분리.

동형이의 문자 사고 — 라틴 a 와 키릴 а 가 식별자에 섞여 들어가면 잡기 힘든 버그. 린터 · 컴파일러 경고를 켜 둠.

모국어 주석을 너무 길게 적으면 읽지 않음 — 같은 정보를 코드 자체로 표현 (이름 · 구조) 하는 편이 우선, 주석은 "왜 이렇게 했는지" 에 집중.

하고픈 말

no-ai-credit
feature-flag-skeptic

모국어로 적는 문서

모국어로 적는 문서

1. 두 종류의 텍스트

2. 유니코드 식별자

3. 다른 길

4. 한국어 문서의 실무

5. 자주 쓰는 모양

6. 자주 걸리는 자리

하고픈 말

Next

philosophy 카테고리의 다른 글

모국어로 적는 문서

모국어로 적는 문서

1. 두 종류의 텍스트

2. 유니코드 식별자

3. 다른 길

4. 한국어 문서의 실무

5. 자주 쓰는 모양

6. 자주 걸리는 자리

하고픈 말

Next

philosophy 카테고리의 다른 글