파이썬 주석 마스터하기: 한 줄 주석부터 Docstring 활용까지 완벽 가이드

파이썬 주석 마스터하기: 한 줄 주석부터 Docstring 활용까지 완벽 가이드

코딩 실력이 쑥쑥 느는 마법같은 비결을 알려드릴게요? 바로 코드에 주석을 잘 다는 것이랍니다! 복잡한 코드 속에서 길을 잃지 않고, 나중에 다시 봐도 이해하기 쉽도록 도와주는 주석은 마치 코드의 친절한 안내자와 같아요. 이 글에서는 파이썬 주석의 모든 것을 파헤쳐, 여러분의 파이썬 코딩 실력을 한 단계 업그레이드 시켜 드릴 거예요~!

파이썬 주석이란 무엇일까요?

파이썬에서 주석(comment)이란 소스 코드에 대한 설명을 덧붙이는 것을 말해요. 프로그램 실행에는 전혀 영향을 주지 않지만, 코드의 이해도를 높이고 유지보수를 편하게 해주는 아주 중요한 존재이죠. 마치 길 찾기 앱의 안내 설명처럼, 코드의 동작 방식을 설명해주고, 어떤 의도로 작성되었는지 알려주는 역할을 한답니다. 주석을 잘 작성하면, 여러분뿐만 아니라 다른 개발자들도 코드를 더 쉽게 이해할 수 있게 되고, 팀 프로젝트에서의 협업도 훨씬 원활해질 거예요.

파이썬 주석 작성 방법: 한 줄 주석과 여러 줄 주석

파이썬에서는 주석을 작성하는 방법이 두 가지가 있어요. 바로 한 줄 주석과 여러 줄 주석이죠.

한 줄 주석 작성하기

한 줄 주석은 # 기호를 사용해 작성해요. # 기호 뒤에 작성하는 모든 내용은 주석으로 처리되어 프로그램 실행 시 무시된답니다.

python
def welcome():
print("Hello, world!") # 이 부분은 한 줄 주석입니다.


위 예시에서 # 이 부분은 한 줄 주석입니다. 는 주석으로, 프로그램의 실행 결과에는 아무런 영향을 미치지 않아요.

여러 줄 주석 작성하기

여러 줄에 걸쳐 주석을 작성하고 싶을 때는 세 개의 작은따옴표 (''') 또는 세 개의 큰따옴표 (""")를 사용해요. 시작과 끝을 모두 세 개의 따옴표로 감싸면 그 사이에 있는 모든 내용이 주석으로 처리된답니다.

“””
이것 또한
여러 줄에 걸쳐 작성된
주석입니다.
“””

def my_function():
“””
이 함수는 어떤 작업을 수행하는 함수입니다.
매우 중요한 기능을 수행하며,
다른 함수와 연동하여 동작합니다.
“””
pass #아직 함수 내용은 구현되지 않았습니다.

작은따옴표와 큰따옴표는 기능상 차이가 없지만, 큰따옴표로 작성된 주석은 Docstring으로 사용되는 경우가 많아요. Docstring은 함수나 클래스의 기능을 설명하는 특별한 주석이라고 생각하면 된답니다.

Docstring의 중요성: 코드 설명의 정석

잘 작성된 Docstring은 코드의 가독성과 유지보수성을 크게 향상시켜줍니다. Docstring은 단순한 주석 이상의 의미를 지니는데요, 함수나 클래스에 대한 상세한 정보를 제공하여 다른 개발자가 코드를 이해하고 사용하는 데 큰 도움을 주죠. 또한, 자동 문서 생성 도구를 사용하여 코드에서 바로 문서를 생성하는 데 활용될 수도 있으며, 이는 개발 효율성을 높이는 데 기여한답니다.

Docstring 작성 방법

Docstring은 함수나 클래스 정의 바로 아래에 세 개의 작은따옴표(''') 또는 큰따옴표(""")로 감싸서 작성해요. 첫 번째 줄은 간단한 요약 설명을, 그 다음 줄부터는 상세한 설명을 작성하는 것이 일반적인 형식입니다.

Args:
    a: 첫 번째 숫자
    b: 두 번째 숫자

Returns:
    a와 b의 합
"""
return a + b

print(calculate_sum.doc) # doc 속성을 통해 Docstring에 접근할 수 있어요.

위 코드처럼 __doc__ 속성을 사용하면 함수의 Docstring에 접근하여 내용을 출력할 수 있어요.

주석 작성 시 주의사항 및 좋은 습관

• 항상 최신 상태를 유지하세요. 코드가 변경될 때마다 주석도 함께 수정하는 것이 중요해요. 오래된 주석은 오히려 혼란을 야기할 수 있답니다.
• 간결하고 명확하게 작성하세요. 너무 길거나 복잡한 주석은 오히려 코드의 가독성을 떨어뜨릴 수 있어요.
• 코드의 의도와 동작 방식을 명확하게 설명하세요. 단순히 코드가 무엇을 하는지가 아니라, 왜 그렇게 작성되었는지에 대한 설명도 포함하는 것이 좋답니다.
• 주석과 코드 사이에 공백을 두어 가독성을 높여주세요.
• 일관성을 유지하며 작성하는 습관을 들이세요. 주석의 스타일과 형식을 일정하게 유지하면 코드 전체의 일관성을 확보하는 데 도움이 된답니다.

주요 내용 정리

항목	설명	예시
한 줄 주석	# 기호를 사용하여 한 줄에 주석을 작성합니다.	# 이것은 한 줄 주석입니다.
여러 줄 주석	세 개의 작은따옴표 (''') 또는 큰따옴표 (""")로 여러 줄 주석을 작성합니다.	''' 이것은 여러 줄<br> 주석입니다. '''
Docstring	함수, 클래스 등에 대한 설명을 작성합니다. __doc__ 속성으로 접근 가능합니다.	""" 이 함수는 두 숫자를 더합니다. """

마무리: 주석 작성으로 파이썬 실력 UP!

이제 파이썬 주석에 대한 모든 것을 알게 되셨나요? 주석은 단순한 설명 이상의 가치를 지닌답니다. 잘 작성된 주석은 여러분의 코드를 더욱 멋지고 효율적으로 만들어 줄 거예요. 오늘부터 바로 주석 작성 습관을 들여, 여러분의 파이썬 코딩 실력을 한 단계 더 높여 보세요! 항상 깔끔하고 이해하기 쉬운 코드를 작성하는 개발자가 되시길 바라면서, 파이썬 주석 정복을 응원합니다~!