[널널한 교수의 고급 파이썬] 05-1 파이썬 주석문과 문서화 문자열

05-1 파이썬 주석문과 문서화 문자열

유지보수란?

• 개발자들이 작성한 코드는 한번 만들고 끝나는 것이 아니며 코드상의 버그가 발견되거나, 인터프리터나 컴파일러의 버전이 업그레이드 될 때, 그리고 기능의 추가가 필요할 때마다 지속적으로 수정되어야 하는데 이러한 작업을 말한다
• 전체 소프트웨어 개발의 많은 비용과 시간이 유지보수에 사용된다

주석문

• 유지보수 작업을 위해서는 반드시 주석문이 필요하다
• 자신이 이전에 만든 코드를 다시 보거나, 전임 개발자가 만든 코드가 어떤 목적으로 만들어졌는가를 후임 개발자들이 빠르게 이해할 수 있다면 유지보수의 시간과 비용이 많이 단축될 것이다
• 따라서 주석문은 프로그램의 필수적인 요소이다
• 하지만 잘못된 주석이나 불필요한 주석은 오히려 코드를 이해하는데 방해가 된다

코드를 이해하는데 도움이 되는 주석문(나쁨)

x = x + 1   # x를 증가시킨다 

코드를 이해하는데 도움이 되는 주석문(좋음)

x = x + 1   # 경계값 x를 증가시킨다 

• 위와 같이 x + 1의 목적이 특정한 경계값 x를 증가시키는 목적이라는 것을 명시해 둔다면 코드를 이해하는데 훨씬 도움이 될 것이다

• 클래스나 함수의 기능을 설명하는 주석문은 삼중 작은따옴표(```)나, 삼중 큰따옴표(""")를 사용하면 매우 유용하다

• 이와 같이 작성된 삼중따옴표 내의 문자열을 파이썬의 문서화 문자열 docstring이라고 한다

def square(a):
    """입력값 a의 제곱을 반환하는 함수"""
    return a**2

print(square.__doc__)
print(help(square))

• 이와 같이 docstring은 코드 내에서 주석으로의 역할도 하지만 최종적으로 완성된 코드에 대한 자동 문서화를 위해서도 필요한 기능이다
• 만일 대화창이나 코드에서 help(square)와 같이 help() 함수를 통해 square()함수를 살펴보면 이 역시 다음과 같이 문서화 문자열에 정의된 내용이 나타나게 된다