Python | 함수 주석(Args, Returns 등) 사용하기

함수 주석, 왜 써야 할까?

인수인계를 받아보니,,,
"이 함수가 뭐 하는 함수지?" 싶은 순간이 꽤 많다.
함수 위에 친절하게 설명이 달려있는 경우, 아주 땡큐베리감사.
이런 설명을 Docstring이라고 하는데, 함수, 클래스, 모듈 어디든 쓸 수 있고,
커서를 올리면 그게 무슨 역할인지 바로 확인해줘서 꽤 유용하다.

Docstring, 어떻게 쓰는 게 좋을까?

사실 일반적으로 아는 방식은 그냥 따옴표 세 개 (""")로 감싸는 것.
그렇지만 좀 더 보기 좋게 쓰고 싶은 게 사람 마음.
대표적으로 Google 스타일이 많이 쓰인다고 한다.

def add(a, b):
	"""
    두 수를 더해서 반환합니다.
    
    Args:
    	a (int): 첫 번째 숫자
        b (int): 두 번째 숫자
    
    Returns:
    	int: 두 수의 합
	"""
    return a + b

이렇게 쓰면

• a와 b가 뭔지
• 반환값이 뭔지
  한 눈에 볼 수 있다.

주요 기능

• Args: 함수에 들어가는 인자(파라미터) 설명
• Returns: 함수가 뭘 반환하는지
• Raises: 함수에서 어떤 에러가 발생할 수 있는지

def divide(a, b):
	"""
    두 수를 나눕니다.
    
    Args:
    	a (float): 분자
        b (float): 분모
        
	Returns:
    	float: 나눈 결과
        
	Raises:
    	ValueError: 분모가 0일 때
	"""
    if b == 0:
    	raise ValueError("분모는 0이 될 수 없습니다.")
	return a / b

인수인계를 받으면서, 백엔드 코드는 기본적인 주석이 달려 있어서 꽤 도움이 됐었는데,
크롤링 소스코드 쪽을 받고 나서 꼼꼼히 달려 있는 Docstring 덕분에
쉽지 않은 내용을 이해하는 데 큰 도움이 됐었던 것 같은,,,

개발할 때마다 매번 Docstring까지 쓰기는 쉽지 않겠지만,
협업을 하거나 인수인계를 할 일이 있다면
Docstring이 너무 큰 도움이 될 것.