스타일 가이드

이 페이지에서는 문서의 언어 스타일 가이드를 설명합니다. reST 파일의 마크업에 관한 자세한 내용은 reStructuredText 마크업을 참조하십시오.

각주

일반적으로 각주는 권장하지 않지만, 특정 정보를 제시하는 가장 좋은 방법인 경우에는 사용할 수 있습니다. 각주 참조를 문장 끝에 추가할 때는 문장 종결 문장 부호 뒤에 배치해야 합니다. reST 마크업은 다음과 같은 형태여야 합니다:

This sentence has a footnote reference. [#]_ This is the next sentence.

각주는 파일 끝에 모아야 하며, 파일이 매우 길다면 절 끝에 모아야 합니다. docutils는 각주 참조로 연결되는 백링크를 자동으로 생성합니다.

적절한 경우 문장 중간에 각주를 넣을 수 있습니다.

대문자 표기

Python 문서에서는 절 제목에 문장식 대문자 표기를 사용하는 것이 바람직하지만, 이 규칙을 따르는 것보다 한 단위 내에서 일관성을 유지하는 것이 더 중요합니다. 대부분의 절이 제목식 대문자 표기를 사용하는 장에 절을 추가하는 경우, 모든 제목을 문장식 대문자 표기로 바꾸거나 새 절 제목에 지배적인 스타일을 사용할 수 있습니다.

특정 규칙에 따라 소문자로 시작해야 하는 단어로 문장을 시작하지 마십시오.

참고

라이브러리 모듈을 설명하는 절의 제목은 흔히 “modulename — 모듈에 대한 간단한 설명.” 형식을 사용합니다. 이 경우 설명은 독립된 문장처럼 대문자로 시작해야 합니다.

Python 문서에서는 운영 체제, 프로그래밍 언어, 표준화 기구 등의 명칭을 비롯한 여러 특수 명칭을 사용합니다. 이러한 대상 대부분에는 특별한 마크업을 지정하지 않지만, 작성자가 Python 문서의 표기 일관성을 유지하는 데 도움이 되도록 Specific words에 권장 표기를 제시합니다.

간단한 언어 사용

가능하면 난해한 표현을 피하십시오. 독자는 전 세계에 있으며 영어 원어민이 아닐 수도 있습니다.

“for example”이나 “that is”와 같은 영어 표현으로 충분한 경우 “e.g.”나 “i.e.” 같은 라틴어 약어를 사용하지 마십시오.

일반적으로 페이지에서 두문자어나 약어를 처음 사용할 때는 전체 표현을 풀어 쓰십시오. 전체 용어를 먼저 쓰고 괄호 안에 두문자어를 표기하는 방식을 권장합니다. 예를 들어 “Basic Multilingual Plane (BMP)”이라고 쓰십시오. “HTML”과 “UTF-8”처럼 일반적으로 널리 알려진 두문자어는 풀어 쓰지 마십시오.

피해야 할 민감한 용어

무신경하거나 배타적인 것으로 여겨질 수 있는 용어를 피하십시오.

피할 표현

대신 사용할 표현

화이트리스트

허용 목록

blacklist

blocklist, denylist

master/slave

main, parent/child, server/client, primary/secondary

특정 단어

일부 용어와 단어는 특별히 언급할 필요가 있습니다. 문서 전체의 일관성을 보장하려면 다음 규칙을 따라야 합니다:

boolean

대부분의 경우 소문자로 씁니다. Boolean mathematics와 Boolean logic에서는 대문자로 씁니다. Python 또는 C 데이터 타입을 지칭할 때는 적절한 마크업을 사용한 정확한 축약 명칭(예: :type:`bool`)을 사용하는 것이 좋습니다.

C API

C 프로그래머가 확장 모듈을 작성할 때 사용하는 Python의 API를 말합니다. 모두 대문자로 쓰고 하이픈을 넣지 않습니다.

CPU

중앙 처리 장치입니다. 풀어 쓸 필요가 없습니다.

free-threaded

전역 인터프리터 잠금(GIL)을 선택 사항으로 만드는 빌드 모드에 선호되는 용어입니다(PEP 703 기준). 이중 부정을 피하려면 “No-GIL”을 사용하지 마십시오(예: “non-no-GIL”).

open source

합성어에 관한 일반적인 영어 규칙을 따릅니다. 형용사로 사용할 때는 하이픈을 넣습니다: “open-source software”. 명사로 사용할 때는 하이픈을 넣지 않습니다: “open source is a collaboration model.”

POSIX

특정 표준 그룹에 부여된 이름입니다. 항상 대문자로 씁니다.

Python

우리가 가장 좋아하는 프로그래밍 언어의 이름은 항상 대문자로 시작합니다.

reST

“reStructuredText”를 뜻하며, Python 문서를 만드는 데 사용하는 읽기 쉬운 일반 텍스트 마크업 구문입니다. 전체 이름으로 표기할 때는 항상 한 단어로 쓰며, 두 형식 모두 소문자 ‘r’로 시작합니다.

시간대

모듈, 클래스 또는 인자와 같은 Python 용어를 지칭할 때는 적절한 마크업을 사용하여 한 단어로 표기하십시오(예: :mod:`timezone`). 현실 세계의 개념을 말할 때는 마크업 없이 두 단어로 표기하십시오.

Unicode

문자 부호화 시스템의 이름입니다. 항상 첫 글자를 대문자로 표기합니다.

Unix

1970년대 초 AT&T 벨 연구소에서 개발한 운영 체제의 이름입니다.

타입 이름

산문에서 타입 이름을 작성할 때는 소스에 나타나는 그대로 이름을 작성하고 클래스 참조 또는 링크되지 않은 클래스 형식으로 스타일을 지정하여 해당 이름이 타입임을 나타내십시오. 예를 들어, dict를 지칭할 때는 :class:`dict`‌ 또는 :class:`!dict`‌ 표기를 사용하십시오.

링크는 guidance on links에 따라 사용해야 합니다.

일부 타입 이름은 Python 외부에서 일반적으로 통용되는 개념이나 명사이기도 합니다. 예를 들어, “tuples”는 tuple 타입과 구별되는 일반적인 프로그래밍 개념입니다. 일반적인 개념을 가리킬 때는 관련 단어를 타입 형식으로 스타일 지정하지 마십시오.

많은 타입에는 실제 타입 이름과 정확히 일치할 수도 있고 그렇지 않을 수도 있는 설명적 이름이 있습니다. 예를 들어, “컨텍스트 변수”는 contextvars.ContextVar를 설명하며, “dict”와 “딕셔너리”는 모두 dict를 설명하는 데 사용됩니다. 텍스트가 특정 타입을 지칭한다는 것이 명확해지면 문맥에 적합한 명칭을 사용하십시오. dict의 경우 “dict”, “딕셔너리” 또는 “:class:`dict`” 중 하나가 가장 적합할 수 있습니다.

설명적 이름은 일반 명사로 작성해야 하므로 문장이나 구의 시작 부분에 있지 않을 때는 소문자로 작성합니다.

Diátaxis

Python 문서는 Diátaxis 프레임워크를 따르기 위해 노력합니다. 이는 작성 중인 문서의 성격에 따라 문체를 조정한다는 의미입니다. 이 프레임워크는 문서를 튜토리얼, 하우투 가이드, 참조 자료, 설명이라는 네 가지 유형으로 구분합니다.

  • The Python Tutorial는 명확해야 하며 독자의 지식에 관해 가정하지 않아야 합니다. 튜토리얼의 목표는 명확하고 논리적인 단계를 통해 사용자가 가능한 한 빨리 Python 코드를 작성하도록 하는 것입니다. 설명과 추상적인 개념은 피해야 합니다. 자세한 내용은 Diátaxis의 Tutorials 가이드를 참조하십시오.

  • Python how-to guides는 사용자가 문제 영역을 헤쳐 나가도록 안내하기 위해 설계되었습니다. 튜토리얼과 하우투 가이드는 모두 설명보다는 지침 제공을 목적으로 하며, 작업을 완료하는 방법을 논리적인 단계로 제시해야 합니다. 그러나 하우투 가이드는 사용자의 지식에 관해 더 많은 것을 가정하며, 사용자가 자신의 특정 문제를 해결하는 최선의 방법을 찾도록 하는 데 중점을 둡니다.

  • The Python Language Reference는 사실에 기반하고 간결해야 합니다. 참조 문서의 목적은 설명하기보다는 기술하는 것입니다. 이 유형의 문서는 권위 있는 출처로 여겨져야 하므로 정확성과 일관성이 핵심입니다. 코드 예제는 이러한 목표를 달성하는 유용한 방법이 될 수 있습니다.

  • Python 해설은 더 깊은 수준의 이해를 제공하며 자연스럽게 더 논의적인 성격을 띱니다. 해설은 독자의 이해를 심화하고 ‘왜’라는 질문에 답하는 것을 목표로 합니다. 해설은 맥락을 제공하고, 주제 간의 연관성을 밝히며, 대안적인 견해를 논의해야 합니다. 해설 전용 섹션은 없지만 Python 문서 전반에서 찾아볼 수 있으며, 그 예로 Unicode HOWTO가 있습니다.

자세한 내용은 Diátaxis 가이드를 참조하십시오.

긍정적 어조

문서는 언어가 무엇을 하는지와 언어를 효과적으로 사용하는 방법을 긍정적으로 명시하는 데 중점을 둡니다.

특정 보안 또는 세그폴트 위험을 제외하면, 문서에서는 “기능 x는 위험합니다” 또는 “전문가 전용”과 같은 표현을 피해야 합니다. 이러한 종류의 가치 판단은 핵심 문서가 아니라 외부 블로그와 위키에 속합니다.

나쁜 예(독자에게 불안감을 조성함):

경고: 파일을 명시적으로 닫지 않으면 데이터가 손실되거나 리소스가 과도하게 소비될 수 있습니다. 파일이 자동으로 닫히도록 참조 횟수 계산에 절대로 의존하지 마십시오.

좋은 예(언어를 효과적으로 사용하는 방법에 관한 확실한 지식 확립):

파일 사용의 모범 사례는 try/finally 쌍을 사용하여 파일을 사용한 후 명시적으로 닫는 것입니다. 또는 with 문을 사용하여 같은 효과를 얻을 수 있습니다. 이렇게 하면 파일이 플러시되고 파일 디스크립터 리소스가 적시에 해제됩니다.

저자 표시

새 문서에는 작성자명(문서의 저자를 명시하는 표기)을 사용하지 마십시오. 저자를 명시적으로 표시하면 다른 사용자가 커뮤니티 문서를 업데이트하기를 꺼리는 경향이 있습니다.

기존 작성자명은 역사적 관심을 위해서만 남아 있습니다. 작성자명은 소유권이나 필수 승인을 의미하지 않으며, 다른 사람의 편집이나 업데이트를 막지도 않습니다.

던더 이름의 발음

__init__ 같은 “던더 이름”은 이어지는 산문에서 어색할 수 있습니다. “an init”입니까, 아니면 “a dunder init”입니까? 밑줄은 무시하고 이름에 포함된 단어에 적합한 관사를 사용하는 것이 좋습니다. 간단한 설문 조사도 이를 뒷받침합니다. “an __init__.”

표현의 경제성

문서가 많다고 해서 반드시 더 좋은 문서인 것은 아닙니다. 되도록 간결하게 작성하십시오.

안타깝게도 문서가 길어지면 이해를 방해할 수 있으며, 텍스트를 잘못 읽거나 잘못 해석할 가능성이 훨씬 더 많아질 수 있습니다. 특수한 사례와 주의 사항으로 가득한 긴 설명은 함수가 실제보다 더 복잡하거나 사용하기 어렵다는 인상을 줄 수 있습니다.

보안 고려 사항(및 기타 우려 사항)

Python과 함께 제공되는 일부 모듈은 모듈의 목적(예: ssl)으로 인해 본질적으로 보안 문제(예: 셸 삽입 취약점)에 노출됩니다. 해당 작업에 대한 Python의 지원에서 특별히 비롯된 문제가 아니라 작업 자체에서 비롯된 문제를 두고 이러한 모듈의 문서 곳곳에 빨간색 경고 상자를 배치하면 읽기 좋은 문서가 되지 않습니다.

대신 이러한 보안 우려 사항은 모듈 문서 내의 전용 “보안 고려 사항” 절에 모아야 하며, 영향을 받는 인터페이스의 문서에서는 "흔한 실수를 피하는 방법에 관한 중요한 정보는 :ref:`security-considerations` 절을 참조하십시오."와 유사한 주석을 사용하여 이를 교차 참조해야 합니다.

마찬가지로 모듈의 여러 인터페이스에 영향을 미치는 흔한 오류가 있다면(예: OS 수준의 파이프 버퍼가 가득 차서 자식 프로세스가 멈추는 경우), 영향을 받는 모든 인터페이스에서 이를 반복하는 대신 “흔한 오류” 절에 문서화하고 교차 참조할 수 있습니다.

코드 예제

짧은 코드 예제는 이해를 돕는 유용한 보조 수단이 될 수 있습니다. 독자는 산문으로 된 형식적인 설명을 이해하는 것보다 간단한 예제를 더 빠르게 파악할 수 있는 경우가 많습니다.

일반적인 사용 사례의 맥락에 맞는 구체적이고 동기를 부여하는 예제가 있으면 더 빠르게 학습할 수 있습니다. 예를 들어 str.rpartition() 메서드는 몬티 파이선 대사의 한 줄에서 마지막 단어를 제거하는 예제보다 URL에서 도메인을 분리하는 예제로 설명하는 편이 더 좋습니다.

관련 sys.ps2 보조 인터프리터 프롬프트의 줄임표는 입력 줄과 출력 줄을 명확하게 구분해야 하는 경우에만 제한적으로 사용해야 합니다. 줄임표는 시각적으로 산만하게 할 뿐만 아니라, 독자가 변형을 실험하기 위해 예제를 복사하여 붙여넣기도 어렵게 만듭니다.

코드 등가물

순수 Python 코드로 된 등가물(또는 근사 등가물)을 제시하면 산문 설명을 유용하게 보완할 수 있습니다. 문서 작성자는 코드 등가물이 가치를 더하는지 신중하게 판단해야 합니다.

좋은 예는 all()의 코드 등가물입니다. 4줄짜리 짧은 코드 등가물은 쉽게 이해할 수 있습니다; 조기 종료 동작을 다시 강조합니다; 이터러블이 비어 있는 경계 사례의 처리 방식도 명확히 보여 줍니다. 또한 all()이 조기 종료될 때마다 False로 평가되는 특정 객체를 반환하도록 하는, 흔히 요청되는 대안을 구현하려는 사람들에게 본보기 역할을 합니다.

좀 더 의문의 여지가 있는 예는 itertools.groupby()의 코드입니다. 이 코드 등가물은 이해를 빠르게 돕는 자료로 쓰기에는 지나치게 복잡하다고 할 만합니다. 복잡하기는 하지만, 대안 구현의 본보기 역할을 하고 “grouper”의 동작을 영어 산문보다 코드로 더 쉽게 보여 줄 수 있으므로 코드 등가물을 유지했습니다.

코드 등가물을 사용하지 말아야 하는 예로는 oct() 함수가 있습니다. 숫자를 8진수로 변환하는 정확한 단계는 함수의 기능을 배우려는 사용자에게 가치를 더하지 않습니다.

대상 독자

자습서(그리고 모든 문서)의 어조는 독자의 지적 능력을 존중해야 합니다. 독자가 어리석다고 가정하지 마십시오. 관련 정보를 제시하고, 동기를 부여하는 사용 사례를 보여 주고, 용어집 링크를 제공하고, 독자가 연관 관계를 파악하도록 최선을 다하되, 독자를 깔보듯 말하거나 시간을 낭비하게 하지 마십시오.

자습서는 초보자를 위한 것이며, 그중 많은 사람이 언어 전체를 평가하기 위해 자습서를 사용할 것입니다. 이 경험은 긍정적이어야 하며, 독자가 실수하면 나쁜 일이 일어날 것이라는 걱정을 남기지 않아야 합니다. 자습서는 지적이고 호기심 많은 독자를 위한 안내서 역할을 하며, 세부 사항은 방법 안내서와 기타 자료에 맡깁니다.

자신의 프로그래밍 오류 중 하나가 정당했다고 인정받으려는, 드물지만 목소리가 큰 부류의 독자가 보내는 문서 변경 요청은 신중하게 받아들이십시오(“제가 실수했으므로 문서가 틀린 것이 분명합니다 …”). 일반적으로 오류를 범한 후에야 문서를 찾아봅니다. 안타까운 일이지만, 일반적으로 문서를 어떻게 수정했더라도 사용자가 언어에 관해 잘못된 가정을 하는 것을 막지는 못했을 것입니다(“저는 …에 놀랐습니다”).

함수 시그니처

다음은 참조 안내서에 함수 시그니처를 포함하는 방법에 관해 계속 발전하고 있는 지침입니다. 관련 Diátaxis에 설명된 대로, 참조 자료는 정확성과 완전성을 우선해야 합니다.

  • 함수가 위치 전용 인자 또는 키워드 전용 인자를 받는다면 적절하게 슬래시와 별표를 시그니처에 포함하십시오:

    .. function:: some_function(pos1, pos2, /, pos_or_kwd, *, kwd1, kwd2):

    이 문법은 간결하지만 함수를 호출할 수 있는 방식을 정확히 나타내며 Python 자체에서 가져온 것입니다.