TigerCow.Door


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


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

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

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


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



0. 문서화


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

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


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



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


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

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


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



1. Docstring 이란?


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

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

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


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


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



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


 


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

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



2. Docstring 사용하기


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


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
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()
cs


https://github.com/doorBW/python_clean_code


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

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

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



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

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




블로그 이미지

Tigercow.Door

Back-end / Python / Database / AI / Algorithm / DeepLearning / etc

댓글을 달아 주세요

파이썬 클린 코드

[해당 리뷰는 터닝포인트 출판사에서 서적을 지원받고 작성하게 되었습니다.]

파이썬 클린코드

기초적인 파이썬 내용을 넘어, 보다 전문적인 파이썬 개발자가 되고자 하는 분

 

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

최근 개인적인 사정으로 인해 블로그에 글을 많이 못올리는데,

오랜만에 IT 도서리뷰로 포스팅을 하게 되었습니다.

이번에 소개해드릴 서적은, 터닝포인트 출판사에서 나온 '파이썬 클린코드'라는 서적입니다.

그럼 간단하게 나마 해당 책에 대한 소개를 드려보도록 하겠습니다.

 

누가 읽으면 좋을까?

사실 이 책에 대해서 이야기를 할 때, 대상 독자에 대한 고려가 제일 필요하다고 생각됩니다.

솔직하게 말씀드려서 아직 파이썬이라는 프로그래밍 언어가 낯설거나, 처음이신분들, 유지보수에 대해서 아직 정확히 파악하지 못했거나 소프트웨어 공학에 대해서 전혀 알지 못하시는 분들에게는 절대 추천드리지 않습니다.

그런 분들께서는 오히려 책의 내용이 지루할 뿐만 아니라, 하나하나 이해하기도 힘들 수 있을 것이라 생각됩니다.

반대로, 파이썬 언어에 대해서 익숙하신 분들, 팀 프로젝트를 하며 코드의 유지보수성에 대해서 고민하신 분들에게는 적극적으로 추천드리고자 하는 책 입니다.

 

소프트웨어 공학의 중요 개념과 파이썬의 연결고리

사실 저는 소프트웨어 공학에 대해서 학습하면서, 당연히 이론적인 내용도 중요했지만 실제로 코드에서 그것들이 어떻게 반영되는지를 무척이나 궁금해했습니다. 하지만 대학에서 이에 대해서 학습할 때에는 자바(Java)언어에 대해 한정적으로 배울 수 있었습니다.

물론 해당 내용이 이론적으로 잘 이해하고 공부한다면 언어는 단순히 도구적으로 사용될 뿐이지만, 개인적으로 파이썬을 좋아하는 개발자로써 파이썬에서의 소프트웨어 공학의 이론들은, 개념들은 어떻게 적용되고 있을까, 실제로 파이썬 언어만의 특징을 어떻게 더 살려낼 수 있을까? 에 대해서 고민한 적이 많습니다.

그리고 이번에 소개시켜드리는 책에서는 그러한 부분들을 많이 해소시킬 수 있었습니다.

책의 목차에서도 그렇듯, '파이썬 클린코드' 서적에서는 우리가 그동안 배웠던 소프트웨어 공학의 내용들과 파이썬 언어만의 특징을 잘 살려내서 설명해주고 있습니다.

 

아쉬웠지만 극복할 수 있는 키워드 설명

책을 읽으면서 아쉬웠던 점은, 가끔 특정 키워드나 개념에 대해 충분한 설명없이 넘어가는 점들이 있습니다.

하지만 이를 '극복할 수 있는' 이라고 말씀드리는 것은, 그러한 것들이 엄청나게 많다거나, 그러한 것들 때문에 다른 내용이 읽히지 않는 정도는 아니기 때문입니다.

오히려 저는 책의 중간중간 포스트잍을 붙여가면서 모르는 키워드에 대해서 정리하고, 그것을 기반으로 해당 챕터의 내용을 다시 상기할 수 있게끔 하는 방법을 사용했는데, 더 공부한 느낌도 나고 정리도 잘 되는 것 같아서 내심 뿌듯했습니다 :)

 


이렇게 '파이썬 클린코드' 서적에 대해 개인적으로 생각하는 특징을 바탕으로 짧게나마 정리해보았습니다.

사실 무엇보다 개인적으로는, 최근 파이썬 언어가 핫해지면서 기초적인 책들이 많이 나오고 있는데, 그 와중에 오랜만에 적당히 깊이있고 잘 정리되어 있는 책이 나와서 너무나 반갑고 재미있게 읽은 책인 것 같습니다.

 

자신이 파이썬 언어에 대해서 보다 깊이 공부하고 싶고, 어느정도 자신이 있다면 꼭 한번 읽어보시기를 적극적으로 추천드립니다.

블로그 이미지

Tigercow.Door

Back-end / Python / Database / AI / Algorithm / DeepLearning / etc

댓글을 달아 주세요