Python – 주석

Python 주석

주석은 코드를 설명하고 문서화하는 데 사용되는 텍스트로, Python 인터프리터에 의해 실행되지 않는다. 좋은 주석은 코드의 가독성을 높이고 다른 개발자나 미래의 자신이 코드를 이해하는 데 도움을 준다.

Python 주석 생성하기

Python에서 주석은 해시 기호(#)로 시작한다. # 기호 뒤에 오는 모든 텍스트는 주석으로 처리되어 실행되지 않는다.

기본 주석 예제

# 이것은 주석입니다

print("Hello, World!")

주석은 코드 실행에 영향을 주지 않으므로 위 코드는 “Hello, World!”만 출력한다.

한 줄 주석

한 줄 주석은 # 기호를 사용하여 작성하며, 코드의 특정 부분을 설명하거나 메모를 남길 때 사용한다.

코드 위에 주석 작성

# 사용자에게 인사말을 출력합니다

print("Hello, World!")

# 변수에 값을 할당합니다

x = 5

y = 10

# 두 수의 합을 계산합니다

sum_result = x + y

print(f"합계: {sum_result}")

코드 끝에 주석 작성

x = 5  # x에 5를 할당

y = 10  # y에 10을 할당

sum_result = x + y  # 두 수를 더함

print(f"합계: {sum_result}")  # 결과 출력

코드 비활성화에 주석 사용

주석을 사용하여 임시로 코드를 비활성화할 수 있다.

print("이 코드는 실행됩니다")

# print("이 코드는 실행되지 않습니다")

print("이 코드도 실행됩니다")

여러 줄 주석

Python에는 공식적인 여러 줄 주석 문법이 없지만, 여러 방법으로 여러 줄 주석을 작성할 수 있다.

방법 1: 각 줄에 # 사용

가장 일반적인 방법으로, 각 줄마다 # 기호를 붙여 주석을 작성한다.

# 이 프로그램은 사용자의 나이를 입력받아

# 내년의 나이를 계산하고

# 결과를 화면에 출력합니다

age = int(input("나이를 입력하세요: "))

next_year_age = age + 1

print(f"내년에는 {next_year_age}살이 됩니다")

방법 2: 삼중 따옴표 사용

삼중 따옴표(“”” 또는 ”’)를 사용하여 여러 줄 문자열을 만들고, 이를 주석처럼 활용할 수 있다.

"""

이것은 여러 줄 주석입니다.

삼중 따옴표를 사용하여 작성했습니다.

기술적으로는 문자열이지만 변수에 할당되지 않으면

주석처럼 동작합니다.

"""

print("Hello, World!")

작은따옴표 3개로도 동일하게 작성할 수 있다.

'''

이것도 여러 줄 주석입니다.

작은따옴표 3개를 사용했습니다.

'''

print("Hello, World!")

💡 여러 줄 주석 주의사항:
• 삼중 따옴표는 기술적으로 문자열이므로 남용하지 말자
• 함수나 클래스의 독스트링과 혼동하지 말자
• 일반적인 주석에는 # 기호 사용을 권장한다
• 코드 블록 전체를 주석 처리할 때만 삼중 따옴표를 사용하자

독스트링 (Docstring)

독스트링은 함수, 클래스, 모듈을 문서화하는 특별한 형태의 주석이다. 삼중 따옴표를 사용하여 작성하며, help() 함수나 IDE에서 자동으로 표시된다.

함수 독스트링

def calculate_area(length, width):

    """

    사각형의 넓이를 계산하는 함수입니다.

    Args:

        length (float): 사각형의 길이

        width (float): 사각형의 너비

    Returns:

        float: 사각형의 넓이

    """

    return length * width

area = calculate_area(10, 5)

print(f"넓이: {area}")

print(help(calculate_area))

클래스 독스트링

class Rectangle:

    """

    사각형을 나타내는 클래스입니다.

    이 클래스는 사각형의 길이와 너비를 저장하고

    넓이와 둘레를 계산하는 메서드를 제공합니다.

    """

    def __init__(self, length, width):

        """

        Rectangle 객체를 초기화합니다.

        Args:

            length (float): 사각형의 길이

            width (float): 사각형의 너비

        """

        self.length = length

        self.width = width

    def area(self):

        """사각형의 넓이를 반환합니다."""

        return self.length * self.width

모듈 독스트링

파일의 맨 위에 작성하여 모듈 전체를 설명한다.

"""

수학 계산 유틸리티 모듈

이 모듈은 기본적인 수학 계산을 위한

함수들을 제공합니다.

Author: 홍길동

Date: 2024-01-01

Version: 1.0

"""

def add(a, b):

    """두 수를 더합니다."""

    return a + b

def multiply(a, b):

    """두 수를 곱합니다."""

    return a * b

주석 작성 모범 사례

효과적인 주석 작성을 위한 지침들을 알아보자.

좋은 주석의 특징

• 코드의 목적과 의도를 명확히 설명한다
• 복잡한 로직을 이해하기 쉽게 설명한다
• 코드만으로는 알기 어려운 비즈니스 로직을 설명한다
• 주의사항이나 제약사항을 명시한다
• TODO나 FIXME 등으로 향후 작업을 표시한다

좋은 주석 예제

def calculate_tax(income, tax_rate):

    """

    소득세를 계산합니다.

    2024년 세법 기준으로 계산하며,

    기본 공제액 150만원이 적용됩니다.

    """

    # 기본 공제액 (2024년 기준)

    basic_deduction = 1500000

    # 과세 소득 계산 (음수가 되지 않도록 보정)

    taxable_income = max(0, income - basic_deduction)

    # TODO: 구간별 세율 적용 로직 추가 필요

    tax = taxable_income * tax_rate

    return tax

# 급여 300만원, 세율 10%로 세금 계산

salary = 3000000

rate = 0.1

tax_amount = calculate_tax(salary, rate)

print(f"세금: {tax_amount:,.0f}원")

피해야 할 주석

다음과 같은 주석은 오히려 코드 가독성을 해친다.

# 나쁜 주석 예제들

x = 5  # x에 5를 할당 (코드와 중복되는 설명)

# i를 1씩 증가시킴

i += 1

# 사용자 이름을 출력

print(user_name)  # 명확한 코드에 불필요한 설명

# 이 함수는 더하기를 수행함

def add(a, b):  # 함수명으로 충분히 알 수 있는 내용

    return a + b

주석 활용 예제

실제 프로그램에서 주석을 효과적으로 활용하는 방법을 살펴보자.

알고리즘 설명 주석

def binary_search(arr, target):

    """

    이진 탐색으로 배열에서 목표값을 찾습니다.

    시간 복잡도: O(log n)

    공간 복잡도: O(1)

    """

    left = 0

    right = len(arr) - 1

    while left <= right:
        # 중간 인덱스 계산 (오버플로우 방지)
        mid = left + (right - left) // 2
        if arr[mid] == target:
            return mid  # 목표값 발견
        elif arr[mid] < target:
            left = mid + 1  # 오른쪽 절반 탐색
        else:
            right = mid - 1  # 왼쪽 절반 탐색
    return -1  # 목표값을 찾지 못함[/code]



설정값과 상수 설명
[code lang="python"]# 애플리케이션 설정

MAX_RETRY_COUNT = 3  # API 호출 최대 재시도 횟수

TIMEOUT_SECONDS = 30  # 네트워크 타임아웃 (초)

CACHE_EXPIRY_HOURS = 24  # 캐시 만료 시간 (시간)

# 수학 상수

PI = 3.14159265359  # 원주율 (소수점 11자리)

EARTH_RADIUS_KM = 6371  # 지구 반지름 (킬로미터)

복잡한 정규표현식 설명

import re

# 이메일 주소 검증 정규표현식

# 구성: 사용자명@도메인명.확장자

# 사용자명: 영문, 숫자, 점, 하이픈, 언더스코어 허용

# 도메인명: 영문, 숫자, 하이픈 허용

# 확장자: 영문 2-6자리

email_pattern = r'^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,6}$'

def validate_email(email):

    """이메일 주소 유효성을 검사합니다."""

    return re.match(email_pattern, email) is not None

주석을 이용한 코드 조직화

주석을 사용하여 코드를 논리적으로 구분하고 구조화할 수 있다.

섹션 구분 주석

# ============================================================================

# 데이터 처리 함수들

# ============================================================================

def load_data(filename):

    """파일에서 데이터를 로드합니다."""

    pass

def clean_data(data):

    """데이터를 정제합니다."""

    pass

# ============================================================================

# 분석 함수들

# ============================================================================

def analyze_data(data):

    """데이터를 분석합니다."""

    pass

def generate_report(analysis_result):

    """분석 결과를 바탕으로 보고서를 생성합니다."""

    pass

# ============================================================================

# 메인 실행 부분

# ============================================================================

if __name__ == "__main__":

    # 1. 데이터 로드

    data = load_data("data.csv")

    # 2. 데이터 정제

    clean_data = clean_data(data)

    # 3. 데이터 분석

    result = analyze_data(clean_data)

    # 4. 보고서 생성

    generate_report(result)

TODO와 FIXME 주석

def process_user_data(user_data):

    """사용자 데이터를 처리합니다."""

    # TODO: 입력값 유효성 검사 추가

    # TODO: 로깅 기능 구현

    # FIXME: 빈 문자열 처리 시 오류 발생

    if user_data:

        processed_data = user_data.strip().lower()

        return processed_data

    # HACK: 임시 해결책 - 추후 개선 필요

    return "default_value"

def calculate_score(points):

    """점수를 계산합니다."""

    # NOTE: 현재는 단순 합계만 계산

    # 향후 가중치 적용 예정

    total = sum(points)

    # WARNING: 점수가 음수일 수 있음

    return total

💡 효과적인 주석 작성 팁:
• 코드가 무엇을 하는지보다 왜 하는지를 설명하자
• 주석과 코드가 일치하도록 유지하자
• 너무 많은 주석보다는 명확한 코드를 작성하자
• 독스트링을 활용하여 함수와 클래스를 문서화하자
• TODO, FIXME 등으로 향후 작업을 명시하자

주석 도구와 확장

주석 작성을 도와주는 도구들을 활용하면 더 효과적으로 코드를 문서화할 수 있다.

IDE 주석 기능

• VS Code: Ctrl+/ (한 줄 주석 토글)
• PyCharm: Ctrl+/ (한 줄 주석), Ctrl+Shift+/ (블록 주석)
• 자동 독스트링 생성 확장 프로그램 활용

문서 생성 도구

• Sphinx: 독스트링을 기반으로 HTML 문서 생성
• pydoc: Python 내장 문서 생성 도구
• MkDocs: 마크다운 기반 문서 생성

적절한 주석은 코드의 품질을 크게 향상시킨다. 코드를 작성할 때 다른 사람이 읽을 것을 고려하여 명확하고 유용한 주석을 작성하는 습관을 기르자.