더북(TheBook)

4.9 독스트링

독스트링(docstring)은 함수 시작 부분에서 함수 인터페이스를 설명하는 문자열이다(docdocumentation의 줄임말이다).

def polyline(t, n, length, angle):

"""n개의 선분을 길이 length만큼,

선분 사이의 각도는 angle만큼 그린다. t는 거북이 객체.

"""

for i in range(n):

t.fd(length)

t.lt(angle)

관례상 모든 독스트링은 삼중 따옴표(""") 문자열을 쓰며, 큰따옴표 3개를 쓰면 문자열을 두 줄 이상 쓸 수 있어서 긴 줄 문자열(multiline string)이라고도 한다.

독스트링은 간결하지만, 이 함수를 사용하는 데 필요한 정보는 들어 있어야 한다. 함수가 어떻게 동작하는지 자세한 것을 모르더라도 함수가 무엇을 하는지 간결하게 설명되어야 한다. 각 인자는 함수의 동작에 어떤 영향을 미치는지, (타입이 명확하지 않다면) 각 인자는 무슨 타입을 써야 하는지를 설명해야 한다.

이러한 문서화는 인터페이스 디자인에서 중요한 부분을 차지한다. 잘 디자인된 인터페이스는 설명하기 쉽다. 따라서 자신이 작성한 함수에 관해 설명하기 어려운 순간이 온다면 아마도 문서화가 아니라 인터페이스 자체를 개선해야 할 것이다.

신간 소식 구독하기
뉴스레터에 가입하시고 이메일로 신간 소식을 받아 보세요.