파이썬 주석/독스트링에 대하여

오픈소스를 분석하다보면 잘 작성된 주석과 독스트링에 고마움을 느끼곤 한다.

잘 설명된 주석과 독스트링이 없었다면, 오픈소스를 분석하는 것에

더 많은 시간을 쏟아야 했을 것이다.

이를 교훈삼아 나도 오픈소스를 개발할 때면, 주석과 독스트링 작성에 더 신경쓰게 되었던 것 같다.

해당 포스팅은 [클린코드, 이제는 파이썬이다] 저서의 일부입니다.

---

주석 Comment

주석은 다음과 같이 나타낼 수 있다.

# comment

'''
This is several rows comment.
we can explain more
'''

주석의 특징

• 코드 행 끝(인라인 주석) 보다는 새로운 행에 독자적으로 작성할 것
• 적절한 대문자를 포함한 하나의 문장으로 작성할 것
• 코드와 마찬가지로 행 길이 제한을 준수할 것
• 인라인 주석은 적어도 코드와 스페이스 2개로 구분하고, # 뒤에 하나의 공백을 둘 것
• URL은 인터넷에서 언제든지 사라질 수 있으니, 가능한 지양할 것

인라인 주석

isMethodsDone = False  # 이렇게 코드 뒤에 따라붙는 주석이 인라인 주석이다

• 행 길이 제한에 맞추어 간략해야 하기 때문에 많은 정보를 담지 못한다.
• 바로 앞에 적힌 코드만 설명해야 한다.
• 위와 같이 변수를 생성할 때, 추가하면 좋다.

설명 주석/요약 주석

# 다음과 같이 이 코드가 작성된 '의도'를 설명한 것이 설명 주석이다
currentWeekAddedTime *= 1.2  # 초과 근무 시간 할당량 반영

# 다음과 같이 아래 코드가 어떤 동작을 수행하는지 간단히 설명한 것이 요약 주석이다.
# 플레이어 차례를 변경
if player = PLAYER_A:
    player == PLAYER_B
else:
    plyaer == PLAYER_A

설명 주석과 요약 주석은 프로그램 이해를 돕는다.
당연히 모든 주석이 프로그램 이해를 돕기위해 쓰여졌겠지만,
단순히 코드를 분석하려는 사람에게
설명주석은 이 코드가 왜 작성되었는지를
요약주석은 필요한 부분만 확인하거나 전체 코드 흐름 파악을 쉽게 해준다.

경험 기반 주석

프로그래머가 개발할 때는 다양한 시도를 거친다.
스택오버플로우를 뒤지거나 다양한 블로그에서 시도한 방법을 따라한다.
같은 오류를 대부분의 프로그래머는 비슷한 방법으로 해결을 시도할 것이다.
내가 시도한 방법과 해결책을 미리 작성해둔다면
뒤에 내 코드를 이어 개발하는 사람이 그 시행착오를 줄일 수 있다.
이런 것이 경험기반의 주르르륵 작성된 주석이다.

법무 정보를 담은 주석

흔히 회사에서 작성한 코드는 파일 맨 앞에 라이센스나 저작권 정보를 담은 주석을 작성하기 마련이다.
이게 너무 길어진다면 모든 정보를 주석으로 다 담기보단
법무 정보가 담긴 웹 페이지를 연결하는 것이 더 깔끔할 수 있다.
물론, 앞서 URL을 피하라고 했지만, 모니터 한 화면이 모두 주석으로 꽉 찬 코드도 좋아보이지 않는다.

TODO 주석

프로그래머가 간혹 자기가 앞으로 해야할 일에 대한 것을 주석으로 남긴다면
코드 태그와 같이 대문자로 표현된 무언가와 함께 작성하게 될 것이다.
대표적인 것이 TODO

while True:  # TODO : 반복 종료 조건 정확하게 명시할 필요
   ...

다음과 같은 다른 태그도 사용해보자

• FIXME : 코드 해당부분이 전혀 동작하지 않음을 상기해야할 때
• HACK : 코드 해당부분이 가까스로 겨우 동작하긴 하는데, 개선이 필요한 경우
• XXX P: 간혹 심각도가 높아지는 일반적인 경고를 담는 경우

독스트링 Doc String

필자는 독스트링을 좋아한다.
오픈소스 분석에서 많은 도움을 받았기 때문이다.
독스트링은 class나 def 뒤에 나오는 다중행 주석이며, IDE에서 도움을 받을 수 있는 정보를 제공하고
혹은 help() 함수로 도움을 줄 수 있다.

아래는 내가 작성하던 오픈소스의 일부이다.

class Painting:
    """Change image to painting image.

    Parameters
    ----------
    img : np.ndarray
        Image that want to work

    Attributes
    ----------
    original_img : np.array
        Input original image
    painting : np.array
        Color clustered image (Applied K-Means Algorithm)
    colors : np.array
        Clustered color data list
    """

    def __init__(self, img):
        ...

이처럼 독스트링은 class의 파라미터, 속성 등에 대한 정보를 담는다.
더 나아가서
Parameters, Returns, Attributes, Note 등의 더 많은 정보를 담을 수도 있다.

그렇다면
앞으로 파이썬을 개발한다면
주석과 독스트링을 간결하고 중요한 의미만 담아서
다른 프로그래머들이 쉽게 알아볼 수 있게 만들어볼 수 있겠는가?