올바른 방법으로 Python 주석 만들기

주석은 프로그래머가 해당 코드가 수행해야 하는 작업을 설명하기 위해 코드에 광고하는 메모입니다. 코드를 행동으로 바꾸는 컴파일러나 인터프리터는 주석을 무시하지만 소프트웨어 프로젝트를 관리하는 데 필수적일 수 있습니다.

주석은 다른 프로그래머에게 Python 코드를 설명하는 데 도움이 되며 선택한 이유를 상기시켜 줄 수 있습니다. 주석은 미래의 프로그래머가 소프트웨어 뒤에 있는 디자인 선택을 이해하도록 도와줌으로써 코드 디버깅 및 수정을 더 쉽게 만듭니다.

주석은 주로 개발자를 위한 것이지만 효과적인 주석을 작성하면 코드 사용자를 위한 훌륭한 문서를 생성하는 데 도움이 될 수 있습니다. Python 프로젝트용 Sphinx와 같은 문서 생성기의 도움으로 코드의 주석은 문서에 대한 콘텐츠를 제공할 수 있습니다.

Python에서 주석 달기의 후드 아래를 살펴보겠습니다.

Python의 주석

Python PEP 8 스타일 가이드에 따르면 주석을 작성할 때 염두에 두어야 할 몇 가지 사항이 있습니다.

• 주석은 항상 완전하고 간결한 문장이어야 합니다.
• 이해하기 어렵거나 부정확한 댓글보다는 아예 댓글을 달지 않는 것이 좋습니다.
• 코드의 변경 사항을 반영하려면 주석을 정기적으로 업데이트해야 합니다.
• 주석이 너무 많으면 주의가 산만해지고 코드 품질이 저하될 수 있습니다. 코드의 목적이 분명한 경우에는 주석이 필요하지 않습니다.

파이썬에서 줄은 # 기호로 시작하면 주석으로 선언됩니다. Python 인터프리터가 코드에서 # 을 발견하면 해당 기호 이후의 모든 항목을 무시하고 오류를 생성하지 않습니다. 한 줄 주석을 선언하는 방법에는 인라인 주석과 블록 주석의 두 가지가 있습니다.

인라인 댓글

인라인 주석은 변수 및 간단한 작업에 대한 간단한 설명을 제공하며 코드 문과 같은 줄에 작성됩니다.

 border = x + 10 # Make offset of 10px

주석은 코드와 동일한 문장에서 코드의 기능을 설명합니다.

댓글 차단

블록 주석은 코드의 복잡한 논리를 설명하는 데 사용됩니다. Python의 블록 주석은 인라인 주석과 유사하게 구성됩니다. 유일한 차이점은 블록 주석이 별도의 줄에 작성된다는 것입니다.

 import csv from itertools import groupby # Get a list of names in a sequence from the csv file with open('new-top-firstNames.csv') as f: file_csv = csv.reader(f) # Skip the header part: (sr, name, perc) header = next(file_csv) # Only name from (number, name, perc) persons = [ x[1] for x in file_csv] # Sort the list by first letter because # The groupby function looks for sequential data. persons.sort(key=lambda x:x[0]) data = groupby(persons, key=lambda x:x[0]) # Get every name as a list data_grouped = {} for k, v in data: # Get data in the form # {'A' : ["Anthony", "Alex"], "B" : ["Benjamin"]} data_grouped[k] = list(v)

블록 주석을 사용할 때 주석은 설명하는 코드 위에 작성됩니다. Python PEP8 스타일 가이드는 한 줄의 코드가 79자를 넘지 않아야 한다고 지시하며 인라인 주석은 종종 이 길이를 초과하여 줄을 밀어냅니다. 이것이 코드를 별도의 줄에 설명하기 위해 블록 주석이 작성되는 이유입니다.

여러 줄 주석

Python은 기본적으로 여러 줄 주석을 지원하지 않으므로 이를 정의하기 위한 특별한 규정이 없습니다. 그럼에도 불구하고 여러 줄에 걸친 주석이 자주 사용됩니다.

각 줄 앞에 # 을 추가하여 여러 줄 주석에서 여러 줄 주석을 만들 수 있습니다.

 # interpreter # ignores # these lines

여러 줄 문자열 구문을 사용할 수도 있습니다. Python에서는 """ , 삼중 큰따옴표 또는 ''' 삼중 작은따옴표로 묶어 여러 줄 문자열을 정의할 수 있습니다.

 print("Multi-Line Comment") """ This String is Multi line """

위의 코드에서 여러 줄 문자열은 변수에 할당되지 않아 문자열이 주석처럼 작동합니다. 런타임에 Python은 문자열을 무시하고 바이트코드에 포함되지 않습니다. 위의 코드를 실행하면 다음과 같은 출력이 생성됩니다.

 Multi-Line Comment

특별 코멘트

코드를 읽을 수 있게 만드는 것 외에도 주석은 Python에서 향후 코드 추가 계획 및 문서 생성과 같은 몇 가지 특별한 목적을 수행합니다.

Python 독스트링 주석

Python에서 독스트링은 주어진 함수나 클래스를 사용하는 방법을 설명하는 여러 줄 주석입니다. 고품질 독스트링을 생성하여 코드 문서화를 개선합니다. 함수나 클래스로 작업하고 내장 help(obj) 함수를 사용하는 동안 독스트링은 개체의 개요를 제공하는 데 도움이 될 수 있습니다.

Python PEP 257은 아래와 같이 Python에서 독스트링을 선언하는 표준 방법을 제공합니다.

 from collections import namedtuple Person = namedtuple('Person', ['name', 'age']) def get_person(name, age, d=False): """ Returns a namedtuple("name", "age") object. Also returns dict('name', 'age') if arg `d` is True Arguments: name – first name, must be string age – age of person, must be int d – to return Person as `dict` (default=False) """ p = Person(name, age) if d: return p._asdict() return p

위의 코드에서 docstring은 관련 함수가 어떻게 작동하는지에 대한 세부 정보를 제공했습니다. Sphinx와 같은 문서 생성기를 사용하면 이 독스트링을 사용하여 프로젝트 사용자에게 이 방법을 사용하는 방법에 대한 개요를 제공할 수 있습니다.

내장 help() 함수를 사용하여 함수 또는 클래스 서명 바로 아래에 정의된 docstring을 반환할 수도 있습니다. help() 함수는 객체 또는 함수 이름을 인수로 취하고 함수의 독스트링을 출력으로 반환합니다. 위의 예에서 get_person 함수와 관련된 독스트링을 표시하기 help(get_person) 를 호출할 수 있습니다. -i 플래그를 사용하여 대화형 셸에서 위의 코드를 실행하면 이 docstring이 Python에 의해 어떻게 구문 분석되는지 확인할 수 있습니다. python -i file.py 를 입력하여 위의 코드를 실행합니다.

help(get_person) 함수 호출은 함수에 대한 docstring을 반환합니다. 출력에는 Python이 자동으로 추가하는 함수 서명 get_person(name, age, d=False) 가 포함됩니다.

get_person.__ doc__ 속성은 프로그래밍 방식으로 독스트링을 검색하고 수정하는 데에도 사용할 수 있습니다. 위의 예에서 "Some more new information"을 추가한 후 help(get_person) 에 대한 두 번째 호출에 나타납니다. 그래도 이렇게 런타임에 docstring을 동적으로 변경해야 할 필요는 없습니다.

TODO 댓글

코드를 작성할 때 개선을 위해 특정 줄이나 전체 블록을 강조 표시하고 싶을 때가 있습니다. 이러한 작업은 TODO 주석으로 표시됩니다. TODO 주석은 코드 업데이트 또는 변경을 계획할 때 또는 파일 코드의 특정 섹션이 작성되어야 함을 프로젝트의 사용자 또는 공동 작업자에게 알리려는 경우에 유용합니다.

TODO 주석은 의사 코드로 작성하면 안 됩니다. 아직 작성되지 않은 코드의 기능을 간략하게 설명하기만 하면 됩니다.

TODO 주석과 한 줄짜리 블록 주석은 매우 유사하며 이들 간의 유일한 차이점은 TODO 주석이 TODO 접두사로 시작해야 한다는 것입니다.

 # TODO Get serialized data from the CSV file # TODO Perform calculations on the data # TODO Return to the user

많은 IDE가 프로그래머를 위해 이러한 주석을 강조 표시할 수 있지만 Python 인터프리터는 TODO 주석을 블록 주석과 다르게 보지 않는다는 점에 유의해야 합니다.

Python 주석 작성 시 모범 사례

신뢰성과 품질을 보장하기 위해 주석을 작성할 때 따라야 하는 여러 모범 사례가 있습니다. 다음은 Python에서 고품질 주석을 작성하기 위한 몇 가지 팁입니다.

명백한 것을 피하십시오

명백한 것을 언급하는 주석은 코드에 어떤 가치도 추가하지 않으므로 피해야 합니다. 예를 들어:

 x = x + 4 # increase x by 4

이 주석은 코드가 수행되어야 하는 이유를 설명하지 않고 단순히 코드가 수행하는 작업을 설명하기 때문에 유용하지 않습니다. 주석은 설명하는 코드의 "무엇"이 아니라 "이유"를 설명해야 합니다.

더 유용하게 재작성하면 위의 예는 다음과 같습니다.

 x = x + 4 # increase the border width

Python 주석을 짧고 부드럽게 유지

의견을 짧고 이해하기 쉽게 유지하십시오. 그것들은 유사 코드가 아닌 표준 산문으로 작성되어야 하며, 실제 코드가 수행하는 작업에 대한 일반적인 개요를 얻기 위해 실제 코드를 읽을 필요를 대체해야 합니다. 너무 많은 세부 사항이나 복잡한 주석은 프로그래머의 작업을 더 쉽게 만들지 않습니다. 예를 들어:

 # return area by performing, Area of cylinder = (2*PI*r*h) + (2*PI*r*r) def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

위의 설명은 독자에게 필요한 것보다 더 많은 정보를 제공합니다. 핵심 논리를 지정하는 대신 주석은 코드의 일반적인 요약을 제공해야 합니다. 이 주석은 다음과 같이 다시 작성할 수 있습니다.

 # return area of cylinder def get_area(r,h): return (2*3.14*r*h) + (2*3.14*r*r)

식별자를 신중하게 사용

식별자는 주석에서 주의해서 사용해야 합니다. 식별자 이름이나 대소문자를 변경하면 독자가 혼동할 수 있습니다. 예:

 # return class() after modifying argument def func(cls, arg): return cls(arg+5)

위의 주석은 코드에서 찾을 수 없는 class 및 argument 를 언급합니다. 이 주석은 다음과 같이 다시 작성할 수 있습니다.

 # return cls() after modifying arg def func(cls, arg): return cls(arg+5)

건식 및 습식

코드를 작성할 때 DRY(자신을 반복하지 마십시오) 원칙을 고수하고 WET(모든 항목을 두 번 작성)를 피해야 합니다.

이는 댓글도 마찬가지입니다. 코드를 설명하기 위해 여러 문을 사용하지 말고 동일한 코드를 설명하는 주석을 단일 주석으로 병합하십시오. 그러나 주석을 병합할 때 주의해야 합니다. 여러 주석을 부주의하게 병합하면 스타일 가이드를 위반하고 독자가 따라가기 어려운 주석이 커질 수 있습니다.

주석은 코드를 읽는 시간을 줄여야 한다는 점을 기억하십시오.

 # function to do x work def do_something(y): # x work cannot be done if y is greater than max_limit if y < 400: print('doing x work')

위의 코드에서 주석은 불필요하게 조각나서 하나의 주석으로 병합할 수 있습니다.

 # function to do x if arg:y is less than max_limit def do_something(y): if y in range(400): print('doing x work')

일관된 들여쓰기

주석이 설명하는 코드와 동일한 수준으로 들여쓰기되었는지 확인합니다. 그렇지 않은 경우 따라가기가 어려울 수 있습니다.

예를 들어, 이 주석은 들여쓰기되지 않았거나 적절하게 배치되지 않았습니다.

 for i in range(2,20, 2): # only even numbers if verify(i): # i should be verified by verify() perform(x)

다음과 같이 다시 작성할 수 있습니다.

 # only even numbers for i in range(2,20, 2): # i should be verified by verify() if verify(i): perform(x)

요약

주석은 이해할 수 있는 코드 작성의 중요한 구성 요소입니다. 댓글을 작성하는 데 투자하는 것은 미래의 자신 또는 코드 기반에서 작업해야 하는 다른 개발자가 높이 평가할 것입니다. 주석을 달면 코드에 대한 더 깊은 통찰력을 얻을 수도 있습니다.

이 자습서에서는 다양한 유형의 Python 주석, 각 주석을 사용하는 시기 및 주석을 만들 때 따라야 할 모범 사례를 포함하여 Python의 주석에 대해 자세히 배웠습니다.

좋은 댓글을 쓰는 것은 공부하고 개발해야 하는 기술입니다. 주석 작성을 연습하려면 돌아가서 이전 프로젝트 중 일부에 주석을 추가하는 것을 고려하십시오. 영감을 얻고 실행 중인 모범 사례를 보려면 GitHub에서 잘 문서화된 Python 프로젝트를 확인하십시오.

자신의 Python 프로젝트를 라이브로 만들 준비가 되면 Kinsta의 애플리케이션 호스팅 플랫폼이 몇 초 만에 GitHub에서 클라우드로 코드를 가져올 수 있습니다.