Python 3에서 주석을 작성하는 방법

소개

주석은 컴파일러와 인터프리터가 무시하는 컴퓨터 프로그램에 존재하는 줄입니다. 프로그램에서 주석을 사용하면 프로그램의 각 부분이 수행하는 작업에 대한 정보나 설명을 제공하므로 사람이 코드를 더 쉽게 읽을 수 있습니다.

프로그램의 목적에 따라 주석은 자신에 대한 메모 또는 알림 역할을 할 수도 있고 다른 프로그래머가 코드가 수행하는 작업을 이해할 수 있도록 작성될 수도 있습니다.

일반적으로 프로그램을 작성하거나 업데이트하는 동안 주석을 작성하는 것이 좋습니다. 나중에 생각한 과정을 잊어버리기 쉽고 나중에 작성된 주석은 장기적으로 덜 유용할 수 있기 때문입니다.

전제 조건

컴퓨터나 서버에 Python 3가 설치되어 있고 프로그래밍 환경이 설정되어 있어야 합니다. 프로그래밍 환경이 설정되지 않은 경우 운영 체제(Ubuntu, CentOS, Debian 등)에 적합한 서버의 프로그래밍 환경에 대한 설치 및 설정 가이드를 참조할 수 있습니다.

주석 구문

Python의 주석은 해시 표시(#)와 공백 문자로 시작하여 줄 끝까지 계속됩니다.

정보: 이 자습서의 예제 코드를 따라하려면 python3 명령을 실행하여 로컬 시스템에서 Python 대화형 셸을 엽니다. 그런 다음 >>> 프롬프트 뒤에 추가하여 예제를 복사, 붙여넣기 또는 편집할 수 있습니다.

일반적으로 주석은 다음과 같이 표시됩니다.

# This is a comment

주석이 실행되지 않기 때문에 프로그램을 실행할 때 거기에 주석 표시가 표시되지 않습니다. 주석은 컴퓨터가 실행하는 것이 아니라 사람이 읽는 소스 코드에 있습니다.

\Hello, World! 프로그램에서 주석은 다음과 같이 표시될 수 있습니다.

# Print “Hello, World!” to console
print("Hello, World!")

목록에서 주석은 다음과 같이 표시될 수 있습니다.

# Define sharks variable as a list of strings
sharks = ['hammerhead', 'great white', 'dogfish', 'frilled', 'bullhead', 'requiem']

# For loop that iterates over sharks list and prints each string item
for shark in sharks:
   print(shark)

주석은 주석을 달고 있는 코드와 동일한 들여쓰기 수준으로 작성되어야 합니다. 즉, 들여쓰기가 없는 함수 정의에는 들여쓰기가 없는 주석이 있고, 뒤따르는 각 들여쓰기 수준에는 주석을 달고 있는 코드와 정렬된 주석이 있습니다.

예를 들어, Python 3 자습서에서 간단한 계산기 프로그램을 만드는 방법의 again() 함수가 코드의 각 들여쓰기 수준 다음에 오는 주석과 함께 주석 처리되는 방법은 다음과 같습니다.

...
# Define again() function to ask user if they want to use the calculator again
def again():

    # Take input from user
    calc_again = input('''
Do you want to calculate again?
Please type Y for YES or N for NO.
''')

    # If user types Y, run the calculate() function
    if calc_again == 'Y':
        calculate()

    # If user types N, say good-bye to the user and end the program
    elif calc_again == 'N':
        print('See you later.')

    # If user types another key, run the function again
    else:
        again()

댓글은 원래 프로그래머이든 프로젝트를 사용하거나 공동 작업하는 다른 사람이든 상관없이 프로그래머를 돕기 위해 만들어집니다. 주석이 코드 베이스와 함께 제대로 유지 및 업데이트될 수 없는 경우 코드와 모순되거나 모순되는 주석을 작성하는 것보다 주석을 포함하지 않는 것이 좋습니다.

코드에 주석을 달 때 무엇 또는 어떻게가 아니라 코드 이면의 이유에 답해야 합니다. 코드가 특별히 까다롭지 않은 한 코드를 보면 일반적으로 코드가 무엇을 하는지 또는 어떻게 하는지 알 수 있습니다.

댓글 차단

블록 주석은 더 복잡한 코드나 독자가 익숙하지 않을 것으로 예상되는 코드를 설명하는 데 사용할 수 있습니다. 이러한 긴 형식의 주석은 뒤따르는 코드의 일부 또는 전체에 적용되며 코드와 동일한 수준으로 들여쓰기됩니다.

블록 주석에서 각 줄은 해시 표시와 단일 공백으로 시작합니다. 둘 이상의 단락을 사용해야 하는 경우 단일 해시 표시가 포함된 줄로 단락을 구분해야 합니다.

다음은 다음에 정의된 main() 함수에서 일어나는 일을 정의하는 블록 주석의 예입니다.

# The main function will parse arguments via the parser variable.  These
# arguments will be defined by the user on the console.  This will pass
# the word argument the user wants to parse along with the filename the
# user wants to use, and also provide help text if the user does not
# correctly pass the arguments.

def main():
  parser = argparse.ArgumentParser()
  parser.add_argument(
      "word",
      help="the word to be searched for in the text file."
  )
  parser.add_argument(
      "filename",
      help="the path to the text file to be searched through"
  )
...

블록 주석은 일반적으로 작업을 이해하기 어려워서 철저한 설명이 필요한 경우에 사용됩니다. 코드에 과도한 주석을 달지 않도록 노력해야 하며 특정 청중을 위해 작성하지 않는 한 다른 프로그래머가 Python을 이해할 것이라고 신뢰하는 경향이 있어야 합니다.

인라인 댓글

인라인 주석은 명령문의 같은 줄에서 코드 자체 뒤에 나타납니다. 다른 댓글과 마찬가지로 해시 표시와 단일 공백 문자로 시작합니다.

일반적으로 인라인 주석은 다음과 같습니다.

[code]  # Inline comment about the code

인라인 주석은 드물게 사용해야 하지만 까다롭거나 복잡한 코드 부분을 설명하는 데 효과적일 수 있습니다. 또한 미래에 작성할 코드의 한 줄을 기억하지 못할 수도 있다고 생각하거나 코드의 모든 측면에 익숙하지 않을 수 있는 사람과 공동 작업을 하는 경우에도 유용할 수 있습니다.

예를 들어 Python 프로그램에서 수학을 많이 사용하지 않는 경우 귀하 또는 귀하의 공동 작업자는 다음이 복소수를 생성한다는 것을 모를 수 있으므로 이에 대한 인라인 주석을 포함할 수 있습니다.

z = 2.5 + 3j  # Create a complex number

다음과 같이 인라인 주석을 사용하여 무언가를 수행하는 이유나 추가 정보를 설명할 수도 있습니다.

x = 8  # Initialize x with an arbitrary number

줄을 서서 하는 설명은 필요한 경우와 프로그램을 읽는 사람에게 유용한 지침을 제공할 수 있는 경우에만 사용해야 합니다.

테스트를 위한 코드 주석 처리

코드를 문서화하는 방법으로 주석을 사용하는 것 외에도 해시 표시는 현재 작성 중인 프로그램을 테스트하거나 디버깅하는 동안 실행하지 않으려는 코드를 주석 처리하는 데 사용할 수도 있습니다. 즉, 새 코드 줄을 구현한 후 오류가 발생하면 정확한 문제를 해결할 수 있는지 확인하기 위해 일부 오류를 주석 처리할 수 있습니다.

해시 마크를 사용하면 코드 설정 방법을 결정하는 동안 대안을 시도할 수도 있습니다. 예를 들어, Python 게임에서 while 루프 또는 for 루프를 사용할지 결정할 수 있으며 테스트 및 결정하는 동안 둘 중 하나를 주석 처리할 수 있습니다. 최선을 다하다:

import random

number = random.randint(1, 25)

# number_of_guesses = 0

for i in range(5):
# while number_of_guesses < 5:
    print('Guess a number between 1 and 25:')
    guess = input()
    guess = int(guess)

    # number_of_guesses = number_of_guesses + 1

    if guess < number:
        print('Your guess is too low')

    if guess > number:
        print('Your guess is too high')

    if guess == number:
        break

if guess == number:
    print('You guessed the number!')

else:
    print('You did not guess the number. The number was ' + str(number))

해시 마크가 있는 코드를 주석 처리하면 다른 프로그래밍 방법을 시도할 수 있을 뿐만 아니라 프로그램의 일부를 체계적으로 주석 처리하고 실행하여 오류의 원인을 찾는 데 도움이 됩니다.

결론

Python 프로그램 내에서 주석을 사용하면 미래의 자신을 포함하여 인간이 프로그램을 더 읽기 쉽게 만들 수 있습니다. 관련성이 있고 유용한 적절한 주석을 포함하면 다른 사람들이 프로그래밍 프로젝트에서 더 잘 협업하고 코드의 가치를 더 명확하게 만들 수 있습니다.

여기에서 Python 프로젝트를 적절하게 문서화하기 위한 더 많은 리소스를 제공하기 위해 PEP 257에서 Python의 Docsstrings에 대해 읽을 수 있습니다.