스타일 가이드

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

각주

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

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

각주는 파일 끝에 모아야 하며, 파일이 매우 길다면 섹션 끝에 모아야 합니다. docutils는 각주 참조로 돌아가는 역링크를 자동으로 생성합니다.

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

대문자 표기

Python 문서에서는 섹션 제목에 문장형 대문자 표기를 사용하는 것이 바람직하지만, 이 규칙을 따르는 것보다 한 단위 내에서 일관성을 유지하는 것이 더 중요합니다. 대부분의 섹션이 제목형 대문자 표기(title case)로 되어 있는 장에 섹션을 추가한다면, 모든 제목을 문장형 대문자 표기로 바꾸거나 새 섹션 제목에 주로 쓰인 스타일을 사용할 수 있습니다.

특정 규칙에 따라 소문자로 시작해야 하는 단어로 문장을 시작하는 것은 피해야 합니다.

참고

라이브러리 모듈을 설명하는 섹션의 제목은 흔히 “modulename — Short description of the module.” 형식을 사용합니다. 이 경우 설명 부분은 독립된 문장처럼 대문자로 시작해야 합니다.

Python 문서에서는 운영 체제, 프로그래밍 언어, 표준화 기구 등의 이름을 포함하여 많은 특수한 이름이 사용됩니다. 이러한 개체 대부분에는 특별한 마크업이 지정되지 않지만, 저자가 Python 문서에서 표현의 일관성을 유지하는 데 도움이 되도록 Specific words에 선호되는 표기가 제시되어 있습니다.

간단한 언어를 사용하십시오

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

“for example”이나 “that is”처럼 영어 단어로 충분한 경우에는 “e.g.”나 “i.e.” 같은 라틴어 약어를 사용하지 마십시오.

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

피해야 할 민감한 용어

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

피할 표현

대신 사용할 표현

whitelist

allowlist

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

중앙 처리 장치(Central processing unit)입니다. 풀어 쓸 필요가 없습니다.

free-threaded

전역 인터프리터 잠금(GIL)을 선택 사항으로 만드는 빌드 모드를 가리킬 때 권장하는 용어입니다(PEP 703에 따름). 이중 부정(예: “non-no-GIL”)을 피하기 위해 “No-GIL”이라는 표현은 사용하지 마십시오.

오픈 소스

복합어에 관한 일반적인 영어 규칙을 따르십시오. 형용사로 쓸 때는 하이픈을 넣습니다: “open-source software”. 명사로 사용할 때는 하이픈을 사용하지 마십시오: “오픈 소스(open source)는 협업 모델입니다.”

POSIX

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

Python

우리가 가장 좋아하는 프로그래밍 언어의 이름은 항상 첫 글자를 대문자로 씁니다.

reST

“reStructuredText”를 가리키며, Python 문서를 만드는 데 사용하는 읽기 쉬운 일반 텍스트 마크업 문법입니다. 풀어 쓸 때는 항상 한 단어로 쓰며, 두 형태 모두 소문자 ‘r’로 시작합니다.

time zone

모듈, 클래스, 인자와 같은 Python 용어를 가리킬 때는 적절한 마크업과 함께 한 단어로 쓰십시오(예: :mod:`timezone`). 현실 세계의 개념을 이야기할 때는 마크업 없이 두 단어로 쓰십시오.

유니코드

문자 인코딩 체계의 이름입니다. 항상 첫 글자를 대문자로 씁니다.

Unix

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

타입 이름

본문에서 타입 이름을 쓸 때는 소스에 나타나는 그대로 타입 이름을 쓰고 클래스 참조나 링크 없는 클래스로 스타일을 지정하여 그 이름이 타입임을 나타내십시오. 예를 들어 dict는 :class:`dict`‌ 또는 :class:`!dict`‌로 가리키십시오.

링크는 링크에 관한 지침에 따라 사용해야 합니다.

일부 타입 이름은 Python 밖에서도 흔히 통용되는 개념이나 명사입니다. 예를 들어 “튜플”은 tuple 타입과는 구별되는 일반적인 프로그래밍 개념입니다. 일반적인 개념을 가리킬 때는 해당 단어를 타입으로 스타일 지정하지 마십시오.

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

서술적인 이름은 일반 명사로 써야 합니다. 즉, 문장이나 구의 시작이 아닐 때는 소문자로 씁니다.

Diátaxis

Python 문서는 Diátaxis 프레임워크를 따르고자 노력합니다. 이는 작성하는 문서의 성격에 따라 글쓰기 스타일을 조정한다는 뜻입니다. 이 프레임워크는 문서를 튜토리얼, 사용법 안내서, 레퍼런스, 설명의 네 가지 유형으로 나눕니다.

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

  • Python 사용법 안내서는 사용자가 특정 문제 영역을 헤쳐 나가도록 안내하기 위한 것입니다. 튜토리얼과 사용법 안내서는 모두 설명보다는 지시를 위한 것이며, 작업을 완료하는 방법을 논리적인 단계로 제시해야 합니다. 그러나 사용법 안내서는 사용자의 지식에 대해 더 많은 것을 가정하며, 사용자가 자신의 특정 문제를 해결하는 가장 좋은 방법을 찾는 데 초점을 맞춥니다.

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

  • Python 설명서는 더 깊은 수준의 이해를 제공하며 본질적으로 더 논술적입니다. 해설 문서는 독자의 이해를 깊게 하고 ‘왜’라는 질문에 답하는 것을 목표로 합니다. 해설 문서는 맥락을 제공하고, 주제 사이를 연결하며, 다른 관점도 논의해야 합니다. 해설 문서만을 위한 섹션은 따로 없지만 파이썬 문서 곳곳에서 찾아볼 수 있으며, 그 예로 Unicode HOWTO가 있습니다.

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

긍정적인 어조

문서는 언어가 무엇을 하는지, 그리고 언어를 어떻게 효과적으로 사용하는지를 긍정적으로 서술하는 데 초점을 둡니다.

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

나쁜 예(독자의 마음에 걱정을 불러일으킴):

경고: 파일을 명시적으로 닫지 않으면 데이터가 손실되거나 자원이 과도하게 소비될 수 있습니다. 파일을 자동으로 닫기 위해 참조 카운팅에 절대 의존하지 마십시오.

좋은 예(언어를 효과적으로 사용하는 방법에 대한 확실한 지식을 제공하는 경우):

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

저자 표기

새 문서에는 바이라인(문서의 저자를 명시하는 것)을 사용하지 마십시오. 저자를 명시적으로 표기하면 다른 사용자가 커뮤니티 문서를 갱신하기를 주저하게 되는 경향이 있습니다.

기존 바이라인은 역사적인 의미만 있습니다. 바이라인은 소유권이나 필수 승인을 의미하지 않으며, 다른 사람의 편집이나 갱신을 막지도 않습니다.

던더 이름의 발음

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

표현의 간결성

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

안타깝게도 문서를 길게 만들면 이해를 방해할 수 있으며, 글을 잘못 읽거나 잘못 해석할 여지가 더욱 많아질 수 있습니다. 예외적인 경우와 주의 사항으로 가득 찬 긴 설명은 함수가 실제보다 더 복잡하거나 사용하기 어렵다는 인상을 줄 수 있습니다.

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

Python과 함께 제공되는 일부 모듈은 모듈의 목적(예를 들어, ssl) 때문에 본질적으로 보안 문제(예를 들어, 셸 주입 취약점)에 노출됩니다. Python이 해당 작업을 지원하는 방식 자체가 아니라 수행하려는 작업 때문에 생기는 문제에 대해 이러한 모듈의 문서를 빨간색 경고 상자로 뒤덮는 것은 좋은 읽기 경험을 주지 못합니다.

대신 이러한 보안 우려 사항은 모듈 문서 안의 전용 “보안 고려 사항” 섹션에 모아 두고, 영향을 받는 인터페이스의 문서에서는 "Please refer to the :ref:`security-considerations` section for important information on how to avoid common mistakes."와 비슷한 참고 문구로 교차 참조해야 합니다.

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

코드 예제

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

사람들은 전형적인 사용 사례의 맥락에 맞는 구체적이고 동기를 부여하는 예제를 통해 더 빨리 배웁니다. 예를 들어, str.rpartition() 메서드는 Monty Python 대사 한 줄에서 마지막 단어를 제거하는 예제보다 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 자체에서 가져온 것입니다.