프로그램이 길어지고 호출해야 하는 함수가 다양한 파일에 존재한다면, 함수 호출을 위해 도움을 줄 수 있는 설명을 달아주는 것이 효율적이다. 여기서는 함수 설명을 어떻게 달 수 있는지와 알아두면 좋은 3가지 항목에 대해서 설명해 보도록 하겠다.
아래와 같이 test 함수가 있다고 치자. 여기에 설명을 달고자 한다면, 쌍따옴표 3개를 이용해서 감싸고 원하는 설명을 넣으면 된다.
def test(a = 'a', b = 1, c = None):
"""
test 함수입니다.
a (str): a value
b (int): b value
c (str): c value
"""
pass
이때, 함수에서 사용되는 인자값(아규먼트, 파라메터)도 함께 기입을 해주면 보다 각 인자값들이 어떻게 사용되는지 쉽게 알 수 있기 때문에 효율성을 높일 수 있다.
1. 들어쓰기
함수 설명은 사람이 읽는 설명서 같은 개념이기 때문에 되도록 쉽게 읽을 수 있도록 작성해 주면좋다.
그리고 Python 특성에 맞게 들어쓰기를 할 경우 설명에서도 구분을 해주기 때문에 보다 가시성을 높일 수 있다.
들어쓰기를 하지 않았을 때줄바꿈도 올바르게 적용이 되지 않는다.
들어쓰기를 했을 때들어쓰기를 기준으로 정렬이 된다.
들어쓰기를 했을때 보다 잘 표현이 되는 이유는 Python 라인 맞춤이 주석에도 동일하게 적용이 되기 때문에, : 와 같은 쌍 따옴표는 파이썬에서 들어쓰기를 하지 않으면 정상적으로 표현이 되지 않는 부분도 읽기를 어렵게 만드는 단점으로 작용한다.
def test(a, b, c):
"""
test 함수입니다.
Args:
a (str): a value
b (int): b value
c (str): c value
Retruns:
None
"""
pass
2. 인자값에 기본값 적용하기
프로그램을 코드를 작성하다보면, 인자값이 선언되지 않았다고 오류가 발생하는 경우가 있다.
이를 쉽게 방지할 수 있는 방법이 바로 기본값을 지정해 두는 것이다.
이렇게 기본값을 지정해 두면 함수를 선언한 효과가 생겨서, 특정 인자를 넘겨주지 않았을 때 기본값으로 동작하게 된다.
그리고 함수 설명에도 어떤 타입(유형, str, int등 인자값 종류)의 인지 값인지 쉽게 확인이 가능하다.
인자값의 타입을 바로 알 수 있다
만약에 값이 없는 경우가 존재하는 인자값에는 None 을 기본값으로 사용하면, None는 없음을 의미하기 때문에 조건식에 사용하기 유용하다.
def test(a = 'a', b = 1, c = None):
"""
test 함수입니다.
Args:
a (str): a value
b (int): b value
c (str): c value
Retruns:
None
"""
pass
3. 강조 사용하기
파이썬 주석에서는물결 무늬 아래 기호(`)를 이용해서 강조를 표현 할 수 있다. 이를 이용하여 특정 강조가 필요한 부분에 적절하게 석어주면, 보다 효과적인 주석을 작성이 가능하다. 필자의 경우 인자 타입에 보통 물결 무늬 아래 기호를 이용해서 강조를 주어 보다 가시성을 높여주도록 사용 한다.
int 주변에 검은색 강조가 들어간다
def test(a = 'a', b = 1, c = None):
"""
test 함수입니다.
Args:
a (str): a value
b `int`: b value
c (str): c value
Retruns:
None
"""
pass
