파이썬 주석, 한줄, 여러줄 범위 주는 방법, 독스트링(docstring)에 대해 정리

파이썬에서는 주석을 달 때 주로 두 가지 방법을 사용합니다.

한 줄 주석

한 줄짜리 짧은 설명을 추가할 때는 # 기호를 사용합니다. # 뒤에 오는 모든 내용은 파이썬 인터프리터가 무시하며, 코드 실행에 영향을 주지 않습니다.

Python

 

# 이것은 한 줄 주석입니다.
print("Hello, world!") # 이 부분도 주석으로 처리됩니다.

 

여러 줄 주석

여러 줄에 걸쳐 긴 설명을 작성하거나 코드 블록 전체를 일시적으로 비활성화하고 싶을 때는 여러 줄 주석을 사용합니다. 파이썬은 여러 줄 주석을 위한 별도의 문법이 없기 때문에, 일반적으로 ''' (작은따옴표 3개) 또는 """ (큰따옴표 3개)로 둘러싸인 문자열 리터럴을 사용합니다. 이 문자열은 변수에 할당되지 않고 독립적으로 사용될 경우, 파이썬 인터프리터가 주석처럼 취급합니다.

Python

 

"""
이것은 여러 줄 주석의 예시입니다.
이 안에 작성된 내용은 모두 코드 실행에 영향을 주지 않습니다.
여러 줄에 걸쳐 상세한 설명을 추가할 때 유용합니다.
"""
def my_function():
    '''
    이 함수는 특별한 기능을 수행합니다.
    사용법:
    1. 데이터를 입력합니다.
    2. 함수를 호출합니다.
    3. 결과를 확인합니다.
    '''
    print("함수 실행!")

위의 예시처럼 함수나 클래스의 첫 줄에 여러 줄 주석을 사용하면 독스트링(docstring)으로 인식되어 해당 객체에 대한 문서를 자동으로 생성하는 데 사용될 수 있습니다.

 

질문을 통해 내용정리)

독스트링(docstring)이 무엇인가요?

 

독스트링(docstring)은 파이썬에서 모듈, 함수, 클래스, 메서드의 정의 바로 아래에 작성되는 문자열입니다. 코드의 목적, 기능, 사용 방법 등을 설명하는 데 사용되며, 파이썬의 여러 줄 주석(""" """ 또는 ''' ''')과 같은 문법을 사용합니다.

 

독스트링의 특징

1. 자동 문서화: help() 함수를 사용하거나 특정 도구(예: Sphinx)를 이용해 코드를 문서화할 때 독스트링이 자동으로 추출됩니다.
2. IDE 지원: 많은 통합 개발 환경(IDE)이나 에디터에서 함수 위에 마우스를 올렸을 때 독스트링 내용을 팝업으로 보여주는 기능을 제공합니다.
3. 접근성: __doc__ 속성을 통해 프로그램 내에서 독스트링에 접근할 수 있습니다.

예시:

Python

 

def add(a, b):
    """두 수를 더한 결과를 반환합니다.

    Args:
        a (int): 첫 번째 숫자
        b (int): 두 번째 숫자

    Returns:
        int: a와 b를 더한 결과
    """
    return a + b

위 코드에서 """...""" 부분이 바로 add 함수의 독스트링입니다. 이 독스트링은 help(add)를 호출하면 출력되고, add.__doc__으로 접근할 수도 있습니다.

 

 

이해하기 쉽게 비유를 들어 설명해 드릴게요.

★ 독스트링(Docstring)은 코드의 '사용 설명서'입니다.

우리가 새로운 전자제품을 사면 사용 설명서가 들어있죠? 이 설명서는 제품의 기능, 사용 방법, 주의사항 등을 알려줍니다. 독스트링이 바로 이런 역할을 합니다.

• 코드의 목적: 이 기능이 무엇을 하는 건지
• 사용 방법: 이 기능을 어떻게 써야 하는지
• 매개변수(Args): 이 기능에 어떤 정보를 줘야 하는지
• 반환 값(Returns): 이 기능이 어떤 결과를 돌려주는지

이 모든 내용을 독스트링에 담아 다른 개발자나 미래의 내가 코드를 쉽게 이해하고 사용할 수 있게 돕는 거죠.

 

 

주석(#) vs. 독스트링(""" """)

두 가지 모두 코드를 설명하는 용도로 쓰이지만, 역할이 조금 다릅니다.

• 주석 (#): 코드의 특정 한 줄이 왜 이렇게 동작하는지 간단하게 설명할 때 사용해요.
  • 예시: "이 변수는 사용자 이름을 저장하기 위해 만들었어."
  Python

   

  # 사용자 이름을 저장하는 변수
  user_name = "Gemini"
  

• 독스트링 (""" """): 함수, 클래스 등 하나의 기능 덩어리에 대한 종합적인 설명을 할 때 사용해요.
  • 예시: "이 함수는 두 숫자를 더하는 기능을 해. 첫 번째 숫자는 'a', 두 번째 숫자는 'b'로 줘야 하고, 더한 결과를 돌려줘."
  Python

   

  def add(a, b):
      """두 수를 더하는 함수입니다."""
      return a + b
  

쉽게 말해, 주석은 '코딩' 과정 중의 메모이고, 독스트링은 '완성된 기능'에 대한 공식 설명서라고 생각하면 됩니다. 독스트링은 help() 같은 파이썬 내장 기능을 통해 접근할 수 있지만, # 주석은 단순히 코드 안에 있는 메모일 뿐이라 접근할 수 없어요. 그래서 독스트링은 문서화에 더 중요한 역할을 합니다.

 

 

★ help() 함수란?

help() 함수를 통해 독스트링에 접근한다는 것은, 파이썬 인터프리터가 코드를 읽어 독스트링을 찾아내고, 그 내용을 사용자에게 보여준다는 뜻입니다.

예를 들어 설명

add라는 함수가 있다고 가정해 봅시다. 이 함수는 두 숫자를 더하는 기능을 합니다.

Python

 

def add(a, b):
    """
    두 개의 숫자를 더하고 그 결과를 반환합니다.

    Args:
        a (int): 더할 첫 번째 숫자
        b (int): 더할 두 번째 숫자

    Returns:
        int: a와 b를 더한 결과
    """
    return a + b

이 코드를 실행하고 나서, help() 함수를 사용해 add 함수에 대한 도움말을 요청하면 다음과 같은 일이 일어납니다.

1. 파이썬 인터프리터에 help(add) 명령을 내립니다.
2. 인터프리터는 add라는 이름의 함수를 찾습니다.
3. 함수 정의 바로 아래에 있는 독스트링("""...""")을 발견합니다.
4. 독스트링의 내용을 화면에 출력해 사용자에게 보여줍니다.

결과 화면:

Help on function add in module __main__:

add(a, b)
    두 개의 숫자를 더하고 그 결과를 반환합니다.

    Args:
        a (int): 더할 첫 번째 숫자
        b (int): 더할 두 번째 숫자

    Returns:
        int: a와 b를 더한 결과

이처럼 help()를 사용하면, 코드를 직접 열어보지 않아도 함수가 어떤 역할을 하는지 독스트링을 통해 바로 알 수 있습니다. 이것이 독스트링이 '자동 문서화' 역할을 하는 중요한 이유입니다.

 

 

 

최종 개념정리 질문)

소스내에서 여러줄을 통째로 해당 함수에 대해 메모를 해둔것을 #으로 한것은 help함수로는 못가져오고, 여러줄을 주석으로 해둔것은 help함수로 해당 함수를 지정하면 통째로 주석 영역의 내용을 바로 볼 수 있다는 건가요?

 

네, 정확히 이해하셨습니다.

 

# 주석 vs. 독스트링(""" """)과 help() 함수

# 기호를 사용한 주석은 파이썬 인터프리터가 단순히 무시하는 "메모" 역할을 합니다. 따라서 # 뒤에 오는 여러 줄의 내용도 help() 함수는 인식하지 못하고 불러올 수 없습니다.

반면, """ 또는 ''' 로 묶인 여러 줄 주석은 함수나 클래스 바로 아래에 위치할 경우 독스트링(docstring)으로 인식됩니다. 이 독스트링은 파이썬이 특별히 관리하는 "공식 설명서" 역할을 하며, help() 함수를 통해 그 내용을 쉽게 불러올 수 있습니다.

간단히 요약하면:

• # 주석: 코드를 보는 사람을 위한 메모일 뿐, help() 함수로는 접근할 수 없습니다.
• 독스트링 (""" """): 코드의 공식 설명서 역할을 하며, help() 함수로 내용을 확인할 수 있습니다.

따라서 함수에 대한 여러 줄의 설명을 남기고 싶다면, # 대신 독스트링을 사용해야 help() 함수로 그 내용을 확인할 수 있습니다.

 

★ 독스트링의 위치관련 내용 정리

독스트링(Docstring)은 정확히는 함수, 클래스, 모듈 등 코드 블록의 첫 번째 문장으로 작성된 여러 줄 주석을 의미합니다. 단순히 '여러 줄 주석'이라고 생각할 수 있지만, 위치와 용도에 따라 특별한 의미를 갖게 됩니다.

독스트링의 위치는 중요합니다. 함수, 클래스 등의 정의 바로 아래에 위치해야 합니다. 만약 함수 바깥에 작성하거나, 함수 내부의 다른 코드 줄 다음에 작성하면 단순한 여러 줄 주석으로 취급되어 독스트링으로 인식되지 않습니다.

올바른 독스트링 위치

Python

 

def my_function(param1):
    """
    이것이 독스트링입니다.
    함수 정의 바로 아래에 위치해야 합니다.
    """
    print(param1)

잘못된 독스트링 위치

Python

 

# 이것은 일반 주석입니다.
def my_function(param1):
    # 이 부분은 주석입니다.
    """이것은 독스트링이 아닙니다."""
    print(param1)

따라서 독스트링은 단순히 여러 줄 주석이 아니라, 특정 위치에 작성되어 자동 문서화 기능을 수행하는 특별한 주석이라고 이해하시면 됩니다.

 

 

질문)

꼭 함수 안쪽에 여러줄의 주석 내용을 작성한것을 독스트링이라고 하나요?

 

꼭 함수 안쪽에만 독스트링을 작성하는 것은 아닙니다. 독스트링은 모듈, 클래스, 함수, 메서드 등 여러 코드 블록의 가장 첫 줄에 작성하는 여러 줄 주석을 의미합니다.

독스트링의 핵심은 "어디에" 위치하느냐 입니다.

 

독스트링의 올바른 위치

• 함수: def 키워드 바로 아래
• 클래스: class 키워드 바로 아래
• 모듈(파일): 파일의 가장 첫 번째 줄

예시:

Python

 

"""
이것은 모듈 독스트링입니다. (파일의 시작에 위치)
"""

class MyClass:
    """
    이것은 클래스 독스트링입니다.
    """
    def __init__(self):
        """
        이것은 메서드 독스트링입니다.
        """
        pass

def my_function():
    """
    이것은 함수 독스트링입니다.
    """
    pass

이처럼 독스트링은 특정 코드 블록의 정의 바로 다음에 위치해야만 help() 함수로 접근할 수 있는 특별한 설명서 역할을 할 수 있습니다. 다른 곳에 위치하면 단순히 여러 줄 주석으로 취급됩니다.