저자: 귀도 반 로섬(Guido van Rossum)
한글판 johnsonj 2008.06.06
XXX 서문.
스타일 지도서는 일관성에 관한 것입니다. 스타일은 일관성이 있어야 합니다. 프로젝트를 수행중일 때는 더 일관성이 있어야 합니다. 모듈이나 함수안에서 일관성을 지키는 일은 더욱 더 중요합니다.
그러나 정말 중요한 것이 있습니다 : 일관적이지 않아야 할 때를 알아야 합니다 -- 단순히 스타일 지도서대로 적용되지는 않는 경우가 있습니다. 잘 모르실 경우에는 스스로 최선의 판단을 하셔야 합니다. 여러 예들을 살펴보고 어떤 것이 가장 좋은지 스스로 결정하십시오. 그리고 주저 없이 물어보시기 바랍니다!
XXX 들어가기.
이맥스(Emacs)에 파이썬 모드가 있습니다. 이 기본값을 사용합시다: 즉, 한개의 들여쓰기 수준당 4개의 공백을 사용하는 것이 좋습니다.
정말 오래된 코드라면 혼란스럽지 않도록 8개 공백에 해당하는 탭을 계속 사용하셔도 좋습니다.
이맥스(Emacs)의 파이썬 모드는 하나의 파일에 가장 많이 사용되는 들여쓰기 수준을 자동으로 탐지해서 들여쓰기 매개변수를 그에 맞추어 설정합니다.
절대로 탭과 공백을 혼용하지 마십시오.
파이썬에서 가장 인기 있는 들여쓰기는 공백만을 사용하는 것입니다. 두번째로 인기 있는 방법은 탭만을 사용하는 것입니다.
탭과 공백을 혼용하여 들여쓰기된 코드는 모두 공백으로 변환시켜야 합니다.(이맥스(Emacs)에서는 전체 버퍼를 선택하고 ESC-x를 쳐서 탭문자들을 없애면 됩니다.)
-t 옵션으로 파이썬 명령어 해석기에 요청하면, 탭과 공백을 불법적으로 혼용한 코드에 대하여 경고를 보내줍니다. -tt 옵션을 사용하면 경고 대신 에러가 뜹니다. 이러한 옵션들을 사용하시기를 강력히 권장합니다!
줄당 80자 언저리로 제한된 장치들이 아직도 많습니다. 그러한 장치라면 기본으로 지정된 자동 줄넘기기는 보기에 흉합니다. 그러므로, 모든 줄을 최대 79 문자로 제한하는 것이 좋습니다. (이맥스(Emacs)는 정확히 80자 길이에서 자동으로 줄넘기기를 합니다.)
기다란 줄을 자동으로 줄넘기기 할 때 선호되는 방법은 반괄호(), 각괄호[], 활괄호{} 안에서 파이썬이 묵시적으로 줄이 연속된다고 가정하는 점을 활용하는 것입니다. 필요하다면 표현식 주위에 괄호 한쌍을 따로 추가할 수도 있습니다. 그러나 어떤 때는 역사선을 사용하는 것이 더 좋게 보일 때도 있습니다. 연속된 줄을 적절히 확실하게 들여쓰기 하십시오.
이맥스(Emacs)의 파이썬 모드는 이것을 정확히 수행합니다. 약간의 예를 들면 다음과 같습니다:
class Rectangle(Blob):
def __init__(self, width, height,
color='black', emphasis=None, highlight=0):
if width == 0 and height == 0 and \
color == 'red' and emphasis == 'strong' or \
highlight > 100:
raise ValueError, "sorry, you lose"
if width == 0 and height == 0 and (color == 'red' or
emphasis is None):
raise ValueError, "I don't think so"
Blob.__init__(self, widt, height,
color, emphasis, highlight)
최상위 함수와 클래스 정의는 두개의 공백 줄로 분리하세요. 한 클래스 안에서의 메쏘드 정의는 한개의 공백줄로 분리시킵니다. 관련된 함수 그룹들을 분리하는데 따로 더 공백줄이 (아주 가끔) 이용되기도 합니다. 공백줄은 한무리의 관련된 한줄짜리 명령어 (예 : 일단의 비실행명령어)사이에서는 생략하기도 합니다.
공백줄을 사용하여 메쏘드 정의를 가른다면, 'class'줄과 그 첫 번째 메쏘드 정의사이에 역시 하나의 공백줄을 둡니다.
함수에는 논리적 구별을 나타내기 위한 공백줄을 아주 아껴서 사용하세요.
나는 다음과 같은 위치에서 공백문자를 사용하는 것을 아주 싫어합니다 :
spam(ham[ 1 ], { eggs: 2 } ).spam(ham[1], {eggs: 2}).if x == 4 : print x , y ; x , y = y , x.if x == 4: print x, y; x, y = y, x. spam (1).spam(1).
dict ['key'] = list [index].dict['key'] = list[index]. x = 1 y = 2 long_variable = 3
이것을 항상 다음과 같이 쓴다
x = 1 y = 2 long_variable = 3
(위의 어떤 사항에 대해서도 나와 다투지 맙시다 -- 나는 이미 20년간이나 이 스타일에 익숙하답니다.)
i = i+1 submitted = submitted + 1 x = x*2 - 1 hypot2 = x*x + y*y c = (a+b) * (a-b) c = (a + b) * (a - b)
def complex(real, imag=0.0):
return magic(r=real, i=imag)
코드에 맞지않는 주석은 주석이 없는 것보다 더 나쁩니다. 코드가 변하면 항상 먼저 주석을 최신으로 유지하려는 노력을 하세요!
주석이 구절이거나 문장이라면, 소문자로 시작하는 식별자가 아닌한 (절대로 식별자의 대소문자를 변경하지 마세요!), 그것의 첫번째 단어는 반드시 대문자로 시작되어야 합니다.
주석이 짧다면, 마지막의 구두점은 생략하는 편이 좋습니다. 블록 주석은 일반적으로 완전한 문장으로 이루어진 하나 이상의 문단들로 구성됩니다. 그리고 각 문장은 반드시 구두점으로 끝나야 합니다.
한 문장을 끝내는 구두점 다음에 두개의 공백을 두어도 됩니다.
영어를 쓸 때처럼 언제나 자신있게 공백을 적용하세요.
영어를 사용하지 않는 나라의 파이썬 프로그래머들에게 드리는 말씀:
여러분의 언어를 사용하지 않는 사람들이 절대로 읽지 않을 것이라고 120% 확신하지 않는한, 영어로 주석을 작성하세요.
블록 주석은 일반적으로 약간의 코드의 (또는 모두) 앞에 적용하고, 그 코드와 동일한 수준에서 들여쓰기를 합니다. 블록 주석에서 각 줄은 (그것이 주석 안쪽의 들여쓰기된 텍스트가 아닌한) #와 한개의 공백으로 시작합니다.
블록 주석 안의 문단은 한개의 #을 포함한 공백줄로 분리합니다. 블록 주석은 위쪽 아래쪽으로 각각 한개의 공백 줄을 두는 것이 가장 좋습니다 (새로운 함수정의 부분이 시작되는 곳에 있는 블록 주석이라면 위쪽은 2개 아래는 1개의 줄을 두는 것이 좋습니다.).
줄 주석은 서술문과 같은 위치에 있는 주석입니다. 줄 주석은 아껴서 사용해야 합니다.
줄 주석은 적어도 서술문으로부터 공백이 2개이상 떨어져 있어야 합니다. 줄주석은 #와 공백 한개로 시작해야만 합니다.
명백한 사실을 줄 주석으로 기술하는 것은 사실 산만스럽고 불필요하니 사용하지 않는 것이 좋습니다:
x = x+1 # Increment x그러나 때로, 이럴때는 유용합니다 :
x = x+1 # Compensate for border
모든 모듈은 보통 문서화 문자열이 있습니다. 그리고 모듈에서 반출된 함수와 클래스도 모두 문서화 문자열이 있습니다. (__init__구성자를 포함하여) 공개 메쏘드도 또한 문서화 문자열이 있습니다.
한 스크립트(독자적 프로그램)에서 문서화 문자열은 "사용법" 메시지로 사용할 수 있어야 합니다. "사용법"은 스크립트가 부정확한 인자 또는 인자를 빼먹고 호출할 때 (또는 "도움을 받기 위해" "-h"옵션을 사용할 때) 출력됩니다.
문서화 문자열은 스크립트의 함수와 명령어 줄 구문 그리고 환경 변수와 파일들에 대하여 문서화를 해 주어야 합니다. 사용법 메시지를 아주 우아하게 (몇개의 화면에) 치장하여 새로운 사용자가 명령어를 적절히 사용할수 있도록 해 주어야만 할 뿐 아니라, 세심한 사용자를 위해서 모든 옵션과 인자에 대하여 완전하게 참조를 제공하여야 합니다.
일관성을 위하여 항상 문서화 문자열 둘레에 """ 삼중 겹따옴표"""를 사용하세요.
문서화 문자열은 두가지 형태가 있습니다 : 한줄 문서화 문자열과 여러줄 문서화 문자열이 그것입니다.
한줄 문서화 문자열은 진짜로 명백한 경우에 사용합니다. 실제로 한줄에 딱 맞습니다. 예를 들면:
def kos_root():
"""Return the pathname of the KOS root directory."""
global _kos_root
if _kos_root: return _kos_root
...
주의사항:
여러줄 문서화 문자열은 다음과 같이 구성됩니다. 한줄 문서화 문자열과 똑 같은 요약 줄 하나, 다음에 공백줄이 하나 따르고, 다음에 더 자세한 설명이 따릅니다. 요약 줄은 자동적으로 인덱스를 하는 도구들이 사용합니다;
요약줄은 한줄에 꼭 맞아야 하고 나머지 문서화 문자열들과 하나의 공백줄에 의하여 나누어진다는 사실을 주의해야 합니다.
전체 문서화 문자열은 첫 번째 줄에 있는 부호와 같은 위치에 들여쓰기 됩니다 ( 아래의 예를 보세요).
문서화 문자열 처리 도구는 문서화 문자열의 첫 번째 줄 이후로 나타나는 첫 번째 비공백줄의 위치와 똑 같은 들여쓰기 위치로 두 번째 이후 줄에서 많은 양의 들여쓰기를 제거해 버립니다. 문서화 문자열에 있는 이후의 줄들의 상대적인 들여쓰기는 유지됩니다.
여러줄 문서화 문자열의 가장 마지막 문단과 닫기 부호 사이에는 공백줄 하나를 삽입하기를 권장합니다. 그리고 닫기 부호는 하나의 줄에 단독으로 놓기를 권장합니다. 이런 식으로, 이맥스(Emacs)의 문단채우기 명령어가 사용될 수 있습니다.
또한 모든 문서화 문자열(한-줄 혹은 여러-줄)의 앞과 뒤에는 한개의 공백줄을 두기를 권장합니다.
클래스를 문서화하는 문서화 문자열은 -- 일반적으로 말해서, 클래스의 메쏘드는 한개의 공백줄로 각각 분리되고, 문서화 문자열은 그 첫번째 메쏘드로부터 한개의 공백 줄만큼 띄울 필요가 있습니다 ; 균형을 위해, 클래스의 머리부와 문서화 문자열 사이에 한 개의 공백줄을 두는 것이 좋습니다. 함수를 문서화 하는 문서화 문자열은 함수의 몸체가 다수의 공백줄로 분리되어 씌여지지 않는 한, 일반적으로 이러한 요구사항을 따를 필요가 없습니다. -- 이러한 경우에는, 문서화 문자열을 다른 섹션으로 다루고, 그것을 하나의 공백줄로 대체하세요.
모듈을 위한 문서화 문자열은 일반적으로 클래스, 예외 그리고 함수들 (그리고 다른 어떠한 객체들)에 대한 목록을 기술해야만 하는데 그것들은 각각에 대하여 한-줄 요약을 가지고 있으며, 모듈에 의하여 반출됩니다. (이러한 요약들은 일반적으로 객체의 문서화 문자열에 있는 요약 줄보다는 덜 상세합니다.)
함수나 메쏘드를 위한 문서화 문자열은 그것의 행위를 요약해야만 하고 인자들과 반환값 그리고 부작용과 예외상황 발생 그리고 호출되었을 때의 제한 상황들에 대하여 문서화를 (가능하다면 모두) 해야 합니다. 선택적 인자는 명료하게 보여 주어야 합니다. 키워드 인자가 인터페이스의 부분인지 아닌지를 문서화 해야 합니다.
클래스를 위한 문서화 문자열은 그것의 행위를 요약하고 공용메쏘드와 실체변수들의 목록을 나열해야 합니다.
만약 클래스가 하부 클래스가 된다면, 그리고 하부클래스와의 부가적인 인터페이스를 가진다면, 이러한 인터페이스는 각각 (문서화 문자열의 형태로) 나열되어져야 합니다. 클래스 구성자는 자신의 __init__메쏘드에 대하여 문서화 문자열로 문서화 되어야 합니다. 각각의 메쏘드들도 자신만의 문서화 문자열로 문서화 되어야 합니다.
하나의 클래스가 또다른 클래스를 하부클래스로 가지고 있고 그의 행위가 거의 그 클래스로부터 상속된다면, 그것의 문서화 문자열은 이 사실을 언급해야 하고, 그 차이를 요약해야 합니다.
"override" 동사를 사용하여 하부클래스의 메쏘드가 상위클래스의 메쏘드를 대체하고 그리고 그것을 호출하지 않는다는 것을 지시하세요; "extend"동사를 사용하여 하부클래스의 메쏘드가 상위클래스의 메쏘드를 호출한다는 것을 (덧붙이자면 자신의 행위에) 지시하세요.
실행중인 텍스트에서 대문자로 함수나 메쏘드의 인자를 언급하는 이맥스(Emacs)의 관례를 사용하지마세요.
파이썬은 대소문자를 구별하며 그리고 인자의 이름은 키워드 인자로 사용될 수 있습니다. 그래서 문서화 문자열은 정확한 인자의 이름을 문서화하여야 합니다. 인자는 두개의 대쉬를 이름과 설명을 구분짓는데 사용하여, 다음과 같이 각각 한 줄에 나열하는 것이 좋습니다:
def complex(real=0.0, imag=0.0):
"""Form a complex number.
Keyword arguments:
real -- the real part (default 0.0)
imag -- the imaginary part (default 0.0)
"""
if imag == 0.0 and real == 0.0: return complex_zero
...
소스파일에 RCS 또는 CVS 표지를 가져야 한다면, 다음과 같이 하세요.
__version__ = "$Revision: 1.4 $" # $Source: /home/guido/ftp/pub/www.python.org/doc/essays/RCS/styleguide.html,v $
이 줄들은 모듈의 문서화 문자열 뒤에 포함되어야 하며, 다른 코드의 앞에는, 위 아래로 하나의 공백줄로 구분해서 포함되어야 합니다.
파이썬 라이브러리의 이름짓기 관례는 약간 혼란스럽습니다. 그래서 이름짓기 관례가 완벽하게 일관성이 있지는 않습니다.-- 그럼에도 불구하고, 아래에 약간의 가이드 라인이 있습니다.
이름짓기 스타일은 많습니다. 무엇에 사용되는지를 보면 각각 어떤 이름 짓기 스타일이 사용되었는지를 알아낼수 있습니다. 일반적으로 자주 보는 이름짓기 스타일은 다음과 같습니다:
또한 짧고 유일한 접두사를 사용하여 관계된 이름들을 무리짓는 스타일도 있습니다. 이 스타일은 파이썬에서 많이 사용되지는 않지만, 완벽을 위해 언급해 둡니다. 예를 들어, os.stat() 함수는 하나의 터플을 돌려주는데 그 터플의 각 항목은 전통적으로 st_mode, st_size, st_mtime 등등과 같은 이름을 가집니다. X11 라이브러리는 모든 공용 함수에 대하여 이끄는 X를 사용합니다. (파이썬에서, 이러한 스타일은 일반적으로 불필요하다고 생각합니다. 속성과 메쏘드의 이름은 객체의 이름으로 접두어가 붙고, 그리고 함수의 이름은 모듈의 이름으로 접두어가 붙기 때문입니다.)
게다가, 다음에 이끄는 또는 끌리는 밑줄문자를 사용하는 특별한 형태가 있습니다. (이것들은 일반적으로 어떠한 경우의 관례와도 결합될 수 있습니다.):
모듈 이름은 혼합(MixedCase)이거나 소문자(lowercase)이면 됩니다. 어떤 것을 사용할지 결정하는 명료한 관례는 없습니다. 한개의 클래스(또는 밀접하게 연관된 많은 클래스들, 또 약간의 부가적인 자원까지)를 반출하는 모듈은 가끔 MixedCase의 형태로 이름지어지며, 모듈의 이름으로 클래스의 이름도 동일하게 짓습니다(예 : 표준 StringIO 모듈). 한 무리의 함수를 반출하는 모듈은 보통 모두 소문자(lowercase)의 형태로 이름을 짓습니다.
모듈의 이름은 화일의 이름에 사상이 되는데, 어떤 화일 시스템은 대소문자를 구별하고 긴 화일 이름을 잘라버리므로, 모듈의 이름을 아주 간결하게 선택해야 합니다. 다른 모듈이름과 대소문자만 달라서 충돌하는 경우가 없도록 해야 합니다. -- 이것은 유닉스에서는 문제가 되지 않습니다. 그러나 코드가 맥이나 윈도우로 이식되면 문제가 발생할 것입니다.
새로이 떠오르는 관례가 하나 있습니다. C 나 C++로 씌여진 확장모듈이 더 높은 수준의 (예를 들어 더욱 객체 지향적인) 인터페이스를 제공하는 파이썬 모듈을 동반할 때, 파이썬의 모듈 이름은 CapWords의 형태를 가지는 반면에, C/C++ 모듈은 모두 소문자로 이름짓고 하나의 이끄는 밑줄 문자를 가집니다 (예를 들어 Tkinter/_tkinter).
"패키지"들은 ("ni"모듈이 지원하는, 모듈의 집합) 일반적으로 모두 소문자의 짧은 이름을 가집니다.
거의 예외없이 클래스 이름은 CapWords 관례를 사용합니다. 내부적으로 사용할 클래스는 이끄는 밑줄문자 하나를 더 사용합니다.
하나의 모듈이 모든 종류의 조건들을 처리하기 위하여 하나의 예외(처리)를 정의한다면, 일반적으로 그것을 "error"혹은 "Error"라고 부릅니다. 내가 아는 한, 내장(확장) 모듈은 "error"(예를 들어 os.error)를 사용하는 반면에, 파이썬 모듈은 일반적으로 "Error"(예를 들어 xdrlib.Error)를 사용합니다.
하나의 모듈에 의하여 반출된 단순한 함수는 CapWords 스타일을 사용하거나 lowercase (또는lower_case_with_underscores) 형태를 사용할 수 있습니다.
특별히 선호하는 바는 없지만, 나는 중요한 기능(예를 들어 nstools.WorldOpen())을 제공하는 함수에는 CapWords 스타일을 사용하고, 반면에 lowercase의 스타일은 "유틸리티"함수(예를 들어 pathhack.kos_root())에 더욱 많이 사용한다고 믿고 있습니다.
(이런 변수들이 하나의 모듈안에서만 사용될 것이라고 가정해 보겠습니다.) 관례는 반출된 함수의 관례와 거의 똑같습니다. "from M import *"의 형식을 통하여 사용되도록 디자인된 모듈은 자신의 전역 변수 (그리고 내부 함수와 클래스)들에 하나의 밑줄문자로 접두사를 붙여서 반출되는 것을 막아야 합니다.
음, 이야기는 함수와 거의 동일합니다. ILU를 사용할 때는 좋은 관례가 있습니다:
ILU 인터페이스를 통하여 노출되는 메쏘드에는 CapWords 스타일을 사용하세요. 객체형의 구현의 일부인, 다른 클래스 또는 함수가 접근하는 메쏘드에는 소문자를 사용하세요.
하부 클래스나 상위 클래스의 속성들이 전혀 충돌하지 않거나 또는 하부 클래스 하나가 실제로 접근할 필요가 있을 때 "내부" 메쏘드와 실체 변수들에는 앞에 하나의 밑줄문자를 사용하세요.
오직 현재의 클래스만이 하나의 속성에 접근하는 것이 중요할 경우에는 (클래스-지역 이름, 파이썬 1.4에서는 강제적임) 앞에 두개의 밑줄문자를 사용하세요. (그러나 파이썬은 뒷문이 많아서 끈질긴 사용자는 그럼에도 불구하고 예를들어, __dict__ 속성을 통하여 접근할 수 있습니다. 오직 ILU 또는 파이썬의 제한된 모드만이 XXX를 할것입니다.