TigerCow.Door


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

이번 포스팅에서는 SOLID 원칙에 대해서 알아봅니다. SOLID는 5가지 원칙을 줄여서 말하는 내용인데, 한번에 5가지 모두를 알아보지 않고, 각 원칙에 대해서 코드로 함께 살펴보며 총 5개의 포스팅으로 나누어 설명드릴 예정입니다.



0. SOLID란?


우선 솔리드, SOLID는 객체 지향 프로그래밍 및 설계의 다섯가지 기본 원칙을 이야기한다. 프로그램이 시간이 지나도 유지 보수 및 확장이 쉬울 수 있도록 하기 위한 원칙이며, 우리가 학습하고자 했던 클린코드를 위한 원칙이기도 하다. 


조금 더 구체적으로, SOLID는 아래와 같은 5가지 원칙을 이야기 한다.


1. Single Responsibility Principle(단일 책임 원칙)


2. Open/Closed Principle(개방/폐쇄 원칙)


3. Liskov Substitution Principle(리스코프 치환 원칙)


4. Interface Segregation Principle(인터페이스 분리 원칙)


5. Dependency Inversion Principle(의존관계 역전 원칙)


이제 우리는 각 원칙에서 강조하는 것과, 실제로 그것을 코드로서 간단하게 살펴보며 이해를 해보도록 하겠다.




1. SRP(Single Responsibility Principle)


단일 책임 원칙(SRP)이란 하나의 클래스는 하나의 책임만 가지며, 그 책임에 대해 완전히 캡슐화 해야 함을 말한다. 

클래스가 하나의 책임만 가진다는 것은, 하나의 클래스는 하나의 일을 담당하고 있으며, 클래스를 변경해야 할 이유는 오직 한가지가 존재한다는 것으로 생각할 수 있다. 이러한 원칙은, 코드의 응집력을 높이는데 도움을 준다. 


간혹 하나의 클래스가 다양한 책임을 지고 있는 경우가 있는데, 이러한 클래스(객체)를 일컬어 신(god) 객체라고 이야기 한다. 이러한 신 객체가 존재하면 시스템에 대한 유지보수가 어려워진다.


어떤 면에서 단일 책임 원칙은, 관계형 데이터베이스 설계에서의 정규화 개념과 유사하다고 생각할 수 있다. 만약 객체의 속성이나 메서드 중에서 서로 특성이 다른 요소(그룹)가 발견되면 그러한 것들을 적절히 분리시켜야 한다.


이제 실제로 코드를 통해 너무 많은 책임을 가진 클래스와, 이를 단일 책임 원칙에 따라 분리한 예제를 살펴보도록 하자.


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
28
class Course:
    """너무 많은 책임을 가진 Course 클래스"""
    
    def __init__(self, code, name, schedule, pf):
        self.code = code
        self.name = name
        self.schedule = schedule
        self.pf = pf
    
    def connect(self, con)->bool:
        """DB connecting"""
        pass
    
    def close(self)->bool:
        """DB close"""
        pass
    
    def get_course_by_pf(self, professor)->list:
        """professor로 강의 찾기 함수"""
        pass
    
    def save_course(self, Course)->bool:
        """DB에 course 저장하기"""
        pass
    
    def update_course(self, code)->bool:
        """특정 code를 가진 course를 DB update 하기"""
        pass
cs

code: https://github.com/doorBW/python_clean_code


먼저 위의 Course 클래스를 살펴보자.

해당 Course 클래스는 너무 많은 책임을 가지고 있다. 클래스의 생성자 __init__함수가 정의되어 있으면서 DB접근과 관련된 함수들도 함께 정의되어 있다.

즉, Course 객체의 속성들에 대한 관리를 하고 있으면서, Course의 DB 내용에 대한 관리도 하고 있다. 이러한 경우 DB에 대한 시스템 변경이 있을 때나, Course의 속성에 대한 변경이 있을 때 동일한 클래스를 수정하고 서로 영향이 없도록 신경써야 한다.

따라서 위와 같은 클래스는 아래와 같이 분리할 수 있다.


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
28
29
30
31
32
33
class Course:
    """SRP원칙을 준수한 Course 클래스"""
    
    def __init__(self, code, name, schedule, pf):
        self.code = code
        self.name = name
        self.schedule = schedule
        self.pf = pf
 
class CourseDB:
    """SRP원칙을 준수한 CourseDB 클래스"""
    def __init__(self, con):
        self.con = con
    
    def connect(self)->bool:
        """DB connecting"""
        pass
    
    def close(self)->bool:
        """DB closing"""
        pass
    
    def get_course_by_pf(self, professor)->list:
        """professor로 강의 찾기 함수"""
        pass
    
    def save_course(self, Course)->bool:
        """DB에 course 저장하기"""
        pass
    
    def update_course(self, code)->bool:
        """특정 code를 가진 course를 DB update 하기"""
        pass
cs

code: https://github.com/doorBW/python_clean_code


이전과 달리 Course 클래스와 CourseDB 클래스로 나누어, DB를 관리하는 클래스를 따로 분리하였다. 

이렇게 됨으로써 각 클래스가 자신이 담당한 하나의 일에 대해서만 책임을 지게 된다.


이번에는 다른 예제를 살펴보자.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
class Human:
    """추상화 과정이 필요한 Human 클래스"""
    def __init__(self, name, sex):
        self.name = name
        self.sex = sex
        
    def go_restroom(self):
        """화장실 가는 함수"""
        if(self.sex == '남자'):
            print("남자화장실로 간다.")
        elif(self.sex == '여자'):
            print("여자화장실로 간다.")
        else:
            print("성별을 지정해주세요.")
 
cs

code: https://github.com/doorBW/python_clean_code


위의 Human 클래스에서는 객체 생성시에 성별을 정의하게 되어있다. 그리고 go_restroom에서는 성별에 따라 분기처리하여 로직을 처리한다. 즉, Human클래스는 성별이 다른 두가지 케이스에 대한 책임을 동시에 가지고 있다. 이러한 경우 Human 클래스를 다음과 같이 추상화시킴으로써 해결할 수 있다.


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
from abc import *
 
class HumanBase(metaclass=ABCMeta):
    def __init__(self, name):
        self.name = name
    
    @abstractmethod
    def go_restroom(self):
        pass
    
class Male(HumanBase):
    def __init__(self, name):
        super().__init__(name)
        self.sex = "남자"
    
    def go_restroom(self):
        print("남자화장실로 간다.")
        
class Female(HumanBase):
    def __init__(self, name):
        super().__init__(name)
        self.sex = "여자"
        
    def go_restroom(self):
        print("여자화장실로 간다.")
cs

code: https://github.com/doorBW/python_clean_code


위와 같이 추상클래스, HumanBase 클래스를 만들어 주었다. 기본적으로 생성시에는 이름만 받고 이를 상속받은 클래스들은 go_restroom을 구현하게끔 하였다.

그리고 HumanBase를 상속받는 Male 클래스와 Female 클래스를 정의함으로써, 성별이 다른 경우에 대해 각 클래스가 유일한 책임을 가지도록 하였다.


이렇게 우리가 SOLID에서 단일 책임 원칙에 대해 알아보면서 대표적인 두가지 예제를 살펴보았다.

첫번째, Course 클래스에서는 단일 클래스에서 너무 많은 액션, 업무를 담당하고 있어 이를 분리함으로써 단일 클래스가 하나의 책임만 가지도록 하였다.

두번째, Human 클래스에서는 보다 높은 추상과 과정을 통해서 각 클래스가 하나의 책임만 가지도록 설정하였다.


이렇게 단일 책임 원칙을 지킨 경우에 클래스에 대한 외부 영향도를 최소화 할 수 있으며, 결국 유지보수나 확장 면에서 보다 효율적일 수 있다.


블로그 이미지

Tigercow.Door

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

댓글을 달아 주세요



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

이번 포스팅에서는 상속과 컴포지션에 대해서 알아보도록 하겠습니다.

어떤 경우에 상속을 쓰는 것이 올바른 것인지, 그리고 파이썬에서 상속과 파이썬을 어떻게 사용하는지에 대해서 코드로 함께 살펴보겠습니다.



1. 상속(Inheritance)


상속이란 기본적으로 자신이 가진 속성과 메소드를 물려주는 클래스(부모클래스, Parent class, Super class)와 이를 물려받는 클래스(자식클래스, Child class, Sub class)로 이루어진다.

객체 지향적 소프트웨어를 디자인하고 구현할 때 상속은 중요한 개념으로, 또 자주 사용된다. 하지만 이를 다시 생각해보자. 상속개념을 활용하면 부모클래스와 자식클래스간에 강력한 결합력(Coupling)이 발생하게 된다.

좋은 코드, 유지보수를 위한 코드를 생각할 때 결합력을 낮추고, 응집도는 높여야 한다고 했는데, 이러한 점을 고려하면 상속이 무조건적으로 좋은 방안은 아닐 수 있다.

즉, 상속이란 것이 좋은 경우와 그렇지 않은 경우를 잘 선별해가며 활용할 수 있어야한다.


만약 새로운 자식클래스를 만들었을 때 해당 자식클래스가 올바르게 정의된 클래스인지 확인하기 위해서는 상속받은 모든 메서드를 실제로 자식클래스에서 사용하는지를 살펴보아야 한다. 만약 대부분의 메소드를 실제로 필요로 하지 않는다면 다음과 같은 이유로 설계상의 실수일 수 있다.


- 부모클래스가 잘 정의된 인터페이스 대신 막연한 정의와 너무 많은 책임을 가진 경우

- 자식클래스가 확장하려고 하는 부모클래스의 적절한 세분화가 아닌경우


따라서, 상속을 쓰는 올바른 경우는 새로 정의하고자 하는 자식클래스가 부모클래스의 기능을 그대로 물려받으면서 이중 특정 기능을 수정하고자 하거나, 추가적인 기능을 구현하고자 할 때이다.


또한 상속에서도, 인터페이스 정의는 또 다른 상속의 올바른 경우로 생각할 수 있다. 어떤 객체에 인터페이스 방식을 강제하고자 할 때, 실제 기능을 구현하지 않은 추상클래스를 만들고, 이를 상속받는 자식클래스에서 실제로 기능을 구현하게 한다. 


그럼 올바르지 않은 상속의 경우는 어떠한 케이스가 있을까? 바로 예시 코드를 살펴보자.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import collections
from datetime import datetime
 
class TransactionalPolicy(collections.UserDict):
    """잘못된 상속의 예시"""
    
    def change_in_policy(self, customer_id, **new_policy_data):
        self[customer_id].update(**new_policy_data)
 
 
policy = TransactionalPolicy({
    "client001":{
        "fee"1000.0,
        "expiration_date": datetime(2020,1,3),
    }
})
 
policy["client001"]
# {'fee': 1000.0, 'expiration_date': datetime.datetime(2020, 1, 3, 0, 0)}
 
policy.change_in_policy("client001",expiration_date=datetime(2020,1,4))
policy["client001"]
# {'fee': 1000.0, 'expiration_date': datetime.datetime(2020, 1, 4, 0, 0)}
 
cs


위의 코드를 살펴보면 TransactionalPolicy 클래스는 파이썬 내장 collections의 사전자료형을 상속받아 구현하였다. 그리고 TransactionalPolicy 클래스에서 사용하고자 하는 change_in_policy 함수를 구현하였다.


이후 policy 라는 TransactionalPolicy 객체를 만들어 추가한 함수를 사용하였다. 이처럼 원하는 기능을 수행하는 클래스를 구현하였지만, 과연 이 클래스가 사전자료형을 상속하는 것이 올바른 것일까? 파이썬에서 객체가 사용가능한 메서드를 출력해주는 dir함수를 이용하여 policy객체가 이용가능한 메서드를 살펴보자.


1
2
3
4
5
6
7
8
dir(policy)
# ['_MutableMapping__marker', '__abstractmethods__', '__class__', '__contains__', '__copy__', '__delattr__',
# '__delitem__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getitem__',
# '__gt__', '__hash__', '__init__', '__init_subclass__', '__iter__', '__le__', '__len__', '__lt__', '__module__',
# '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__reversed__', '__setattr__', '__setitem__',
# '__sizeof__', '__slots__', '__str__', '__subclasshook__', '__weakref__', '_abc_impl',
# 'change_in_policy', 'clear', 'copy', 'data', 'fromkeys', 'get', 'items',
# 'keys', 'pop', 'popitem', 'setdefault', 'update', 'values']
cs


policy 객체를 보면 우리가 추가로 구현한 change_in_policy 라는 함수 이외에도 다양한 함수가 있다. 정말 해당 객체에서 pop, popitem 등의 함수가 필요로 한 것일까? 필요하지 않을텐데 포함되어 있다. 더군다나 해당 함수들은 public 메서드이기 때문에 이를 사용하게 될 가능성도 있다. 이러한 것을 살펴보아, TransactionalPolicy 클래스가 사전자료형을 상속받은 것은 올바르지 않다고 볼 수 있다.


더군다나, 의미적으로 보았을 때 부모클래스로부터 상속을 받은 자식클래스는 개념적으로 확장되거나, 세부적이라는 것을 의미해야 한다. 하지만 TransactionalPolicy 클래스가 사전자료형에 대해서 개념적으로 확장되거나 세부적이라는 것이라고 생각할 수 있을까?


그럼, 우리는 TransactionalPolicy 클래스를 정의하기 위해서 어떻게 해야할까?


이러한 경우 컴포지션이라는 개념을 활용해볼 수 있다.



2. 컴포지션(Composition)


컴포지션이란, 상속과 다르게 단순히 사용한다는 개념이다. 즉, 기존의 상속 개념에서의 자식클래스가 부모클래스의 모든 속성을 물려받는게 아니라, 자식클래스가 필요한 속성만 부모클래스로부터 가져와 사용하는 것이다.

일반적으로 상속은 암시적 선언이라고 하며, 컴포지션은 명시적 선언이라고 한다.


그럼 바로 컴포지션은 어떻게 사용되는지 위에서의 예시를 가져와 살펴보자.


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
28
class NewTransactionalPolicy:
    """컴포지션을 활용한 예시"""
    
    def __init__(self, policy_data, **extra_data):
        self._data = {**policy_data, **extra_data}
    
    def change_in_policy(self, customer_id, **new_policy_data):
        self._data[customer_id].update(**new_policy_data)
        
    def __getitem__(self, customer_id):
        return self._data[customer_id]
    
    def __len__(self):
        return len(self._data)
 
new_policy = NewTransactionalPolicy({
    "client001":{
        "fee"1000.0,
        "expiration_date": datetime(2020,1,3),
    }
})
 
new_policy["client001"]
# {'fee': 1000.0, 'expiration_date': datetime.datetime(2020, 1, 3, 0, 0)}
 
new_policy.change_in_policy("client001",expiration_date=datetime(2020,1,4))
new_policy["client001"]
# {'fee': 1000.0, 'expiration_date': datetime.datetime(2020, 1, 4, 0, 0)}
cs


이전의 예시와 달리 NewTransactionalPolicy 클래스에서는 사전자료형을 상속받지 않았다.

하지만 __init__함수에서 _data를 private로 선언하면서 사전자료형의 데이터로 초기화한다. 그리고 이후 우리가 사용하고자 하는 change_in_policy함수와 __getitem__함수에서 _data, 즉 사전 자료형을 활용하여 구현하고자 하는 기능을 구현하였다.


이렇게 직접 사전자료형을 상속받지 않고, 단순히 사전자료형을 가져와서 사용하였다.

이를 통해 추후 사전자료형에서 변경이 발생하더라도 그 인터페이스만 잘 유지된다면 NewTransactionalPolicy에서는 별도의 변경이 필요없다. 더군다나 이전에 dir함수를 통해 policy 객체가 사용가능한 메서드를 살펴본 것 처럼 new_policy 객체를 살펴보면 다음과 같다.


1
2
3
4
5
6
dir(new_policy)
# ['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__',
#  '__getattribute__', '__getitem__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__',
#  '__len__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__',
#  '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__',
#  '_data', 'change_in_policy']
cs


확실히 상속을 받았던 policy 객체에 비해, 사용 가능하지만 필요하지 않았던 함수가 사라진 것을 확인할 수 있다.



이렇게 상속과 컴포지션은 단순히 별개의 것이 아니라, 기존의 클래스를 재사용하는 상황에 있어서, 상속을 사용해야 할지 컴포지션을 사용해야 할 지 신중히 판단해야 한다. 단순히 현상황만을 고려한다기 보다는 상속과 컴포지션의 특성과, 장단점을 잘 생각하고 활용해야 새롭게 정의하는 클래스가 추후 가져올 문제를 최소화 할 수 있다.



블로그 이미지

Tigercow.Door

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

댓글을 달아 주세요


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

이번 포스팅에서는, 파이썬에서 제공되는 annotation에 대해서 알아보도록 하겠습니다.



1. Annotation 이란?


우선 Annotation의 사전적 정의는 "주석"이다. 즉, 쉽게 말해서 코드에 대한 추가적인 설명을 이야기하는 무언가를 의미한다.

대표적으로 Java언어에서 함수나 클래스 상단에 @를 통해 annotation을 표시한다.



위는 java의 spring 프레임워크를 사용한 코드 중 일부인데, 10번, 13번, 16번 라인을 보면 @를 통해 annotation을 사용하고 있음을 볼 수 있다. 물론 자바에서의 annotation과 파이썬에서의 annotation은 차이가 있을 수 있다. 하지만 기본적으로 로직이 되는 코드를 "도와주는" 의미에서는 크게 다르지 않다고 볼 수 있다.

(사실 java의 annotation과 같은 것을 파이썬에서는 decorator로 나타내기 때문에 엄밀히 말했을 때, 자바의 annotation과 파이썬의 annotation은 다르다고 볼 수 있다.)


보다 자세히, 파이썬에서의 annotation에 대해서 알아보자.

사실 파이썬에서는 annotation에 대한 강제성이 전혀 없다. 우리가 파이썬에서 #을 이용하거나, 지난 포스팅에서 알아본 docstring과 같이 안써도 되지만, 보다 좋은 코드가 될 수 있도록 추가적으로 관리해주는 것 중 하나일 뿐이다.

파이썬에서 사용하는 annotation의 기본 아이디어는, 코드를 사용하는 이에게 함수나 클래스에 대해 그 인자값의 형태 또는 반환값을 알려주자는 것이다.


함수에 대해서는 함수의 인자에 대한 타입에 대한 힌트를 적거나, 함수의 return값에 대한 타입을 알려줄 수 있다. 또한 파이썬 3.6이후로는 변수에 대해서도 직접 annotation을 달 수 있다. 즉, 클래스에서 사용되는 변수값에 대해 그 타입을 적어둘 수 있다는 것이다.



2. Annotation 사용하기


백문이 불여일견, 우선 Annotation을 사용한 파이썬 코드를 살펴보자.


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
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
#-*- coding:utf-8 -*-
class AnnotationClassExample:
    """
    Annotation에 대한 예시를 확인하기 위한 class입니다.
    __annotation__ 속성을 통해
    class할당되는 first_param과 second_param에 대한 타입을 확인할 수 있습니다.
    """
    first_param: str
    second_param: int
 
    def set_first_param(self, value: str-> None:
        """
        AnnotationClassExample 클래스의
        first_param 값을 바인딩합니다.
        함수의 반환은 없습니다.
        """
        self.first_param = value
 
    def set_second_param(self, value: int-> bool:
        """
        AnnotationClassExample 클래스의
        second_param 값을 바인딩합니다.
        함수의 반환은 True or False 입니다.
        """
        if type(value) == int:
            self.second_param = value
            return True
        else:
            self.second_param = 0
            return False
 
def main():
    print("Annotation 만들어보기")
    new_class = AnnotationClassExample()
    print("\n* AnnotationClassExample 클래스의 annotations")
    print(new_class.__annotations__)
    print("\n* set_first_param 함수의 annotations")
    print(new_class.set_first_param.__annotations__)
    print("\n* set_second_param 함수의 annotations")
    print(new_class.set_second_param.__annotations__)
 
if __name__ == '__main__':
    main()
cs


https://github.com/doorBW/python_clean_code


위의 코드에서는 AnnotationClassExample 클래스와 그 내부에 2개의 변수를 가지고 있으며, 클래스 내부에 2가지 함수를 추가로 구현해두었다. 


우선 함수에 대한 annotation을 살펴보자.

11번, 19번 라인의 함수선언부를 살펴보면 함수의 인자에 대한 annotation과 함수의 return에 대한 annotation이 적용되었다. 이를 통해 함수를 사용하고자 하는 이는 함수의 인자가 어떤 타입을 가져야하는지, 그리고 함수를 통해 얻게되는 값의 타입은 무엇인지 보다 쉽게 알 수 있다.

또한 파이썬 3.6부터 변수에 대한 annotation이 가능하다고 했는데, 이는 8번, 9번 라인과 같이 클래스 내부의 변수에 대한 annotation으로 사용할 수 있다. 


이렇게 annotation을 적용하면, 그 개체에 대해 __annotations__ 이라는 속성이 생긴다. 그리고 해당 속성을 통해 우리가 적용해둔 annotation 값을 볼 수 있는 것이다.

실제로 위의 코드를 실행시켜 보면 main함수내에서 각 클래스와 함수에 대해 __annotations__ 속성을 호출하고, 그 결과는 다음과 같다.



우리가 코드에서 적용시켜준 annotation들이 출력되는 것을 확인할 수 있다.


위와 같이 annotation을 통해 함수나 변수 등에 미리 타입에 대한 힌트를 적어둘 수 있다.

물론 이 또한 파이썬에서 강제성이 있거나, 지켜야 한다는 것은 아니다. annotation은 말 그대로 '힌트'를 주는 것에 불과하다.





블로그 이미지

Tigercow.Door

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

댓글을 달아 주세요


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


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

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

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


이번 포스팅에서는 그 첫번째로, 파이썬의 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

댓글을 달아 주세요