[Python] 파이썬으로 주석을 달아보자!!

📌 이슈 사항

주석은 코드의 가독성을 높이고, 특정 코드의 목적을 설명하는 데 사용된다.

이번 인수인계 받은 파이썬 프로젝트(FastAPI)에서 소스코드에 대한 설명이 전혀 작성되어 있지 않아서,

이번에 주석을 달면서 기능 개선을 하려고 한다.

(주석 하나 안 달아 놓은 건 무슨 심보인가? 🤯)

 

파이썬 주석에 대해서 찾아보니 클래스(class), 함수(function), 메서드(method) 등에 주석을 다는 방법은 여러 가지가 있다는 것을 알게 되었다.

 

 

 

---

 

 

1️⃣ 한 줄 주석

• 한 줄 주석은 # 기호를 사용하여 작성된다.

# 이것은 한 줄 주석입니다.
x = 10  # 변수 x에 10을 할당

 

 

2️⃣ 여러 줄 주석

• 여러 줄 주석은 일반적으로 큰따옴표(""" """") 또는 작은따옴표(''' ''')를 사용하여 작한다.
• 여러 줄 주석은 실제로 문자열 리터럴로 인식되며 변수에 할당되지 않으면 코드에서 무시된다.

"""
이것은 여러 줄 주석 ~~
여러 줄에 걸쳐 설명을 작성 ~~
"""

 

 

3️⃣ 문서화 문자열

• 문서화 문자열은 클래스, 함수, 메서드 등에 대한 설명을 문서화하기 위해 사용된다.
• """ """ 또는 ''' '''을 사용하며, 첫 번째 줄에는 간단한 설명을, 이후에는 더 상세한 설명을 작성한다.

함수

def add(a, b):
    """두 수를 더하는 함수.

    매개변수:
    a (int): 첫 번째 숫자
    b (int): 두 번째 숫자

    반환값:
    int: 두 숫자의 합
    """
    return a + b

클래스

class Calculator:
    """간단한 계산기 클래스."""

    def add(self, a, b):
        """두 숫자의 합을 반환."""
        return a + b

    def subtract(self, a, b):
        """두 숫자의 차를 반환."""
        return a - b

 

4️⃣ 타입 힌트와 사용

• 파이썬 3.5부터는 타입 힌트를 사용 가능하며, 함수의 입출력 타입을 명확하게 할 수 있다.

def multiply(a: int, b: int) -> int:
    """두 수를 곱하는 함수.

    매개변수:
    a (int): 첫 번째 숫자
    b (int): 두 번째 숫자

    반환값:
    int: 두 숫자의 곱
    """
    return a * b

 

5️⃣ Google 스타일

• Google 스타일의 Docstring은 파라미터와 반환값을 명확하게 표시하는 방식이다.

def divide(a: int, b: int) -> float:
    """두 수를 나누는 함수.

    Args:
        a (int): 분자
        b (int): 분모

    Returns:
        float: 나눈 결과 값

    Raises:
        ZeroDivisionError: b가 0일 때 예외 발생
    """
    if b == 0:
        raise ZeroDivisionError("0으로 나눌 수 없습니다.")
    return a / b

 

6️⃣ NumPy 스타일

• NumPy 스타일의 Docstring은 Returns 부분에서 numpy.array 등의 자료형을 보다 명확히 표시할 때 유용하다.

def power(base: int, exp: int) -> int:
    """
    주어진 숫자를 거듭제곱하는 함수.

    Parameters
    ----------
    base : int
        밑(base) 숫자
    exp : int
        지수(exponent)

    Returns
    -------
    int
        base의 exp 거듭제곱 결과
    """
    return base ** exp

 

 

---

 

📌 정리

주석 방식	사용 목적
# 한 줄 주석	: 간단한 설명 추가
""" """ 여러 줄 주석	: 블록 주석, 코드 설명
Docstring	: 함수, 클래스, 모듈 문서화
Google 스타일	: 가독성이 높은 문서화
NumPy 스타일	: 과학 계산 및 데이터 분석용 문서화

 

 

 

이제 프로젝트에서 올바른 주석 스타일을 적용하여 가독성과 유지보수성을 높여 보도록 하자! 🚀