Python에서 코드를 주석 처리하는 방법: 인라인, 여러 줄 및 Docstring

 

How to Comment Code in Python: Inline, Multiline, and Docstring | The Renegade Coder

 

2020년을 시작하면서 제가 가장 좋아하는 콘텐츠인 Python “how to” 콘텐츠로 돌아가고 싶었습니다.

오늘은 우리 모두가 갖추어야 할 기술인 Python으로 코드를 주석 처리하는 방법을 살펴보겠습니다.

 

요약하자면, Python에서 주석을 작성하는 세 가지 주요 방법이 있습니다. 

인라인 주석을 작성하려면 해시 표시 #를 사용합니다. 여러 줄 주석을 작성하려면 모든 줄에 해시 표시를 사용합니다. 혹은 삼중 따옴표 '''를 사용합니다.

 

 이는 주석을 시뮬레이션하는 데 사용할 수 있는 여러 줄 문자열을 시작합니다. 자세한 내용은 아래 옵션을 확인하십시오.

 

문제 설명

이 시리즈 전체에서 제가 일관성 있게 진행 했던 것은 특정 문제를 대상으로 하는 콘텐츠를 만들고 몇 가지 솔루션으로 해결하는 것입니다. 

물론 이러한 솔루션 중 상당수는 Python 작동 방식에 대한 기본적인 이해가 필요합니다.

 다시 말해서, 저는 그 어떤 기초에 대한 글도 실제로 써본 적이 없습니다. 뭐 그래도, 저는 아예 안하는 것보다는 낫다고 생각합니다.

 

오늘은 파이썬에서 코드를 주석 처리하는 몇 가지 방법을 살펴보려고 합니다. 모르는 사람들을 위해 주석은 코드를 직접 문서화하는 방법입니다. 특히 주석은 프로그램에 의미론적 영향을 미치지 않는 텍스트입니다. 즉, 주석은 독자에게 컨텍스트를 제공하는 것 외에는 아무 것도 하지 않습니다.

 

예제로, 다음과 같이 피타고라스 정리와 같은 수학적 표현을 작성하고 싶을 수 있을 것입니다:

a_squared = 3**2
b_squared = 4**2
c_squared = a_squared + b_squared

 

명백히 이 표현식은 변수 이름 선택에만 기반한 피타고라스 정리와 유사합니다.

하지만 모든 사람이 언뜻봐서는 알 수는 없습니다. 즉, 독자에게 이 표현의 목적이 무엇인지 알려주는 주석을 추가하기를 원할 수도 있다는 뜻이죠. 예를 들어, "피타고라스 정리를 사용하여 c^2를 계산합니다."라고 말할 수 있습니다. 그럼 이렇게 하려면 어떻게 해야 할까요? 운 좋게도 이 기사에서는 몇 가지 옵션을 제공합니다.

 

솔루션

기사의 이 부분에서는 Python에서 주석을 작성하는 몇 가지 다른 방법을 살펴보겠습니다.

 이것은 주석 스타일에 대한 기사나 주석 작성 방법에 대한 해설이 아님을 명심하십시오. 

대신, 우리는 단지 구문을 공유할 것입니다. 제공된 도구를 어떻게 사용할지 결정하는 것은 사용자의 몫입니다.

 

인라인 주석

Python에서는 해시 표시 #를 사용하여 주석을 작성할 수 있습니다. 이 표시가 나타나자 마자 줄 끝까지 이어지는 모든 항목은 주석으로 간주됩니다:

# Uses the Pythagorean Theorem to compute c^2
a_squared = 3**2
b_squared = 4**2
c_squared = a_squared + b_squared

 

주석은 해시 표시가 나타날 때까지 시작되지 않으므로 행의 끝도 주석 처리할 수 있습니다:

# Uses the Pythagorean Theorem to compute c^2
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

 

일반적으로 저는 귀하의 코드가 기본적으로 자체 문서화되어야 한다고 생각합니다. 즉, 여기 저기에 인라인 댓글이 있으면 자신을 포함하여 미래의 독자에게 도움이 될 수 있을 것입니다.

 

인라인 주석을 사용한 블럭 주석

재미있는 사실: Python에는 블록 주석이 없습니다. 즉, 여러 줄 주석을 처리하기 위한 기본 제공 구문이 없습니다. 결과적으로 PEP 8은 블록 주석에 대해 반복되는 인라인 주석을 사용할 것을 권장합니다:

# Uses the Pythagorean Theorem to compute c^2.
# First, we compute a^2 and b^2. Then, the
# expression is constructed as a^2 + b^2 and
# assigned to c^2.
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

 

 

다시 말하지만, 이러한 의견은 아마도 과도할 것입니다. 그들의 역할은 블록 주석의 예를 제공하는 것입니다.

 

여러 줄 문자열을 사용하여 블록 주석

이 모든 것을 통해 여러 줄 문자열로 블록 주석을 시뮬레이션할 수 있습니다:

"""
Uses the Pythagorean Theorem to compute c^2.
First, we compute a^2 and b^2. Then, the
expression is constructed as a^2 + b^2 and
assigned to c^2.
"""
a_squared = 3**2  # Computes a^2
b_squared = 4**2  # Computes b^2
c_squared = a_squared + b_squared  # Computes c^2

 

이제, 그것은 나에게 조금 더 깨끗해 보입니다. 또한 제 생각에는 소스 코드에서 관리하기가 조금 더 쉽습니다.

 

그렇지만, 이것은 진정한 주석이 아님을 명심하십시오. 대신 변수에 할당되지 않은 문자열 상수를 만들어 준 것입니다. 실제로는 문자열이 바이트 코드에서 최적화되기 때문에 이것은 실제로 문제가 되지 않습니다.

 

또 다른 주의 사항: 때때로 이러한 스타일의 주석은 docstring으로 해석될 수 있습니다. 예를 들어 함수 헤더 바로 아래에 이 주석을 삽입하면 문서화 목적으로 docstring이 생성됩니다:

def pythagorean_theorem(a, b):
  """
  Computes the length of the squared third leg of a right triangle.
  """
  a_squared = a**2
  b_squared = b**2
  c_squared = a_squared + b_squared
  return c_squared

 

이 예에서 여러 줄 주석은 실제로 메서드를 문서화하는 데 사용할 수 있는 docstring입니다.

def pythagorean_theorem(a, b):
  """
  Computes the length of the squared third leg of a right triangle.
  :param a: the length of the first leg of the triangle
  :param b: the length of the second leg of the triangle
  :return: a^2 + b^2
  """
  a_squared = a**2
  b_squared = b**2
  c_squared = a_squared + b_squared
  return c_squared

그러면 이 docstring이 함수의 런타임 속성이 됩니다. 즉, 해당 속성을 다음과 같이 검사할 수 있습니다.

print(pythagorean_theorem.__doc__)

보시다시피 일반 주석과 다르게 docstring은 런타임에도 여전히 존재한다는 점에서 일반 주석과 다릅니다. 

 그러면 많은 IDE 및 기타 도구에서 문서화 목적으로 이러한 docstring을 추출할 수 있습니다. 얼마나 멋진가요?

 

도전 과제

여기쯤에서 보통 성능을 측정하곤 하는데 그게 적용이 될 것 같지는 않네요. 그 대신 바로 도전하러 갑시다!

 

이제 Python에서 코드를 주석 처리하는 세 가지 다른 방법을 알았으므로 좋은 주석 처리 방법에 대해 이야기해 보겠습니다. 아래 주석에서 코드에 주석을 달 때 권장하는 팁을 하나 이상 공유하십시오. 댓글 스타일부터 댓글 에티켓까지 무엇이든 자유롭게 공유하세요. 파이썬과 관련된 모든 것에 대해 보너스 포인트가 있습니다.

 

항상 그렇듯이, 나는 아래에 내 자신의 팁도 공유할 것입니다! 가능하다면 약간의 토론을 하고 싶습니다. 진행 상황에 따라 다른 기사로 결과를 정리할 수도 있습니다.

 

약간의 요약

그것으로 우리는 모두 끝났습니다. 항상 그렇듯이 다음은 Python 코드에 주석을 추가하는 세 가지 방법에 대한 간략한 요약입니다.

# Here is an inline comment in Python
 
# Here
# is
# a
# multiline
# comment
# in
# Python
 
"""
Here is another multiline comment in Python.
This is sometimes interpretted as a docstring,
so be careful where you put these.
"""

이상.