파이썬(PYTHON) 클린코드 #1_ Docstring

안녕하세요. 문범우입니다.

파이썬 언어를 활용하는데 보다 좋은 코드, 유지보수가 가능한 코드, 팀원들과 함께 협업할 수 있는 코드를 작성하기 위해 다양한 방법을 알아보고자 합니다. 흔히들 이야기 하듯, 클린코드를 작성하는 방법에 대해서 파이썬에서는 어떻게 구현될까를 함께 알아볼 것 입니다.

물론 클린코드라는 것에 정확한 방법과 기준은 없습니다. 하지만 함께 알아보는 내용들을 통해 그를 위한 다양한 방법과 방향에 대해서는 알아볼 수 있을 것 입니다. 

하나씩 공부해보며 자신의 상황과 프로젝트에 맞게 적용시키면 좋을 것 같네요.

이번 포스팅에서는 그 첫번째로, 파이썬의 docstring에 대해서 알아보도록 하겠습니다.

---

0. 문서화

Docstring에 대해서 알아보기전에 문서화에 대해서 한번 짚어보자.

프로젝트를 진행해보거나, 다른 개발자와 함께 협업을 진행해본 개발자라면 '문서화'가 왜 필요한지 어느정도 느꼈을 수 있다.

여러분들은 지금 개발하고 있는 프로젝트, 지금 작성한 코드를 한달, 일년뒤에 보았을 때 코드를 작성할 때와 같이 부드럽게 코드리딩이 가능한가? 사실 한달, 일년도 아니다. 복잡한 로직과 다양한 처리를 진행하는 개발을 진행할 때면 당장 내일에 그 코드를 정확히 기억하기 힘든 경우도 많을 것이다.

물론 그렇게 리딩이 어렵다는 것은 로직 자체가 깔끔하지 못하다는 문제이지 않을까란 생각을 할 수도 있을 수 있다. 당연히 그 또한 중요하겠지만, 만약 내가 작성한 코드를 다른 동료 개발자가 본다면 어떠할까? 로직이 깔끔하지만 수많은 함수와 클래스들의 코드를 직접 리딩해가며 모든 로직을 '코드'만으로 이해하고 받아들인다는건 상상하는 것보다 매우 힘든 일이 될 수 있다.

하지만 만약 각각의 함수와 클래스, 기타 등등이 어떤 기능을 하는 것인지 알아볼 수 있도록 '문서화'를 해두었다면 어떨까? 내가 작성한 코드를 매우 오랜만에 보더라도 해당 함수의 매개변수는 어떤 타입인지, 해당 함수가 어떤 기능을 하는 것인지, 그리고 반환 값은 무엇인지 한번에 알아 볼 수 있어 해당 함수를 이용하거나 받아들이는데 매우 편리할 것이다. 

즉, 문서화를 통해서 구현된 코드에 대해 보다 명확하고 편리하게 설명할 수 있으며 특정 함수나 클래스 등을 다른 곳에서 사용하고자 할 때 그것들에 대해 손쉽고 명확하게 이해하고 사용할 수 있어 추가적인 개발에 있어 사전에 버그를 방지할 수 있을 것이다.

물론 위에서 이야기한 내용보다 '문서화'가 필요하고 중요한 이유는 더 다양하고 더 중요한 이유들이 있을 수 있지만 이정도라면 개발자 누구나 '문서화'가 왜 필요한지 어느정도 스스로 생각해 볼 수 있는 계기가 될 것이라 생각한다.

1. Docstring 이란?

그럼 왜 필자는 Docstring에 대한 이야기에 앞서 문서화를 이야기했을까?

Docstring은 쉽게 생각했을 때, 코드에 포함된 문서(Document)이다. 즉, 코드에 대한 문서화를 코드 밖에, 워드나 한글 파일, 엑셀을 이용해 따로 하는 것이 아니라 코드 내부에 문서화를 실시한다는 것이다.

특히나 파이썬과 같은 동적 타입의 언어이기 때문에 코드내부에 문서를 포함시키는 docstring 이 매우 좋다. 파이썬에서는 파라미터의 타입을 체크하거나 강제하지 않는다. 헌데 특정 함수나 클래스를 이용하거나 수정하고자 할때 그에 대한 설명이 명확하게 나와있다면 그러한 이용이나 수정이 매우 간편하게 진행될 것이다.

파이썬에서 docstring은 함수나 클래스 모듈등에 정의할 수 있다. 그리고 작성한 내용을 확인하기 위해서는 해당 객체의 __doc__ 라는 속성을 이용하면 된다. (더블언더바)

docstring에 대한 사용법을 알아보기 이전에 실제로 docstring이 정의된 예시를 확인해보자.

위의 사진은 파이썬에서 개체의 길이를 구하는데 사용하는 len함수의 docstring을 출력한 사진이다. 또 다른 예시는 dictionary개체의 docstring을 살펴보자.

 

위와 같이 dictionary 개체의 docstring을 보니, 어떻게 사용하는지도 설명을 첨부하였다.

만약 우리가 dictionary가 무엇인지 궁금했다면 이와 같이 docstring을 통해서 간략하게나마 확인할 수 있을 것이다.

2. Docstring 사용하기

그럼 직접 우리가 클래스나 함수에 대해서 Docstring을 만들어서 사용해보도록 하자.

class DocstringClassExample():
    """
    DocstringClassExample() 예제 클래스
    class에 대한 설명을 함께 적어준다.
    """
 
    def docstring_func_example():
        """
        Return 0 always
        """
        print("ocstring_func_example 함수를 실행하였습니다.")
        return 0
 
def main():
    print("Docstring 만들어보기")
    new_doc = DocstringClassExample()
    print("Class docstring start")
    print(new_doc.__doc__)
    print("Class docstring end")
    print()
    print("Function docstring start")
    print(new_doc.docstring_func_example.__doc__)
    print("Function docstring end")
 
 
if __name__ == '__main__':
    main()

https://github.com/doorBW/python_clean_code

위와 같이 간단한 Class 하나와 함수하나를 만들었다.

docstring은 위와 같이 클래스나 함수 선언 바로 하단부에 따옴표 세개를 이용하면 된다.(쌍따옴표, 홀따옴표 무관하다.)

이렇게 만든 코드를 실행시켜보면 다음과 같이 결과가 출력된다.

docstring 자체를 만들어내는 것, 이를 사용하는 것은 함께 알아본 것 처럼 전혀 어렵지 않고 너무 간단하다.

하지만 보다 중요한 것은 이러한 기능을 놓치지 않고 이용하면서 보다 유지보수 좋은 코드를 지속적으로 만들어 나가는 것, 그리고 기존에 있던 docstring을 최신으로 유지하는 노력일 것이다.

---