[Python] 주석(Comment)

작업을 하다보면 하루 혹은 몇 개월전에 작업했던 함수 혹은 변수가 어떤 역할을 했었는지 다 기억할 수 없다. 이를 위해 주석이라는 요소가 있는데. 모든 프로그래밍 언어들이 다 똑같은 주석방식을 사용하지 않아서 새로운 언어를 접할때면 주석에 대해서도 다시 공부를 해야한다. 그래서 이번엔 파이썬 코드의 가독성을 높이고 협업을 원활하게 하는 데 필수적인 요소인 주석(Comment)에 대해 알아보자.

 

주석은 코드를 실행할 때는 아무런 영향을 주지 않지만, 개발자들에게는 코드의 목적, 작동 방식, 그리고 중요한 세부 사항을 알려주는 매우 중요한 역할을 한다.

잘 작성된 주석은 미래의 자신이나 다른 개발자들이 코드를 이해하고 유지보수하는 데 큰 도움을 준다.

 

1. 주석을 다는 방법: # 과 """

파이썬에서 주석을 다는 방법은 크게 두 가지가 있다.

 

1.1. 한 줄 주석: # (샵) 사용

가장 일반적인 방법으로, 코드 한 줄이나 코드의 특정 부분에 대한 설명을 추가할 때 사용한다. # 기호 뒤에 오는 모든 내용은 파이썬 인터프리터가 무시한다.

# 이 줄은 주석이다. 이 내용은 실행되지 않는다.
print("Hello, Python!") # 이 부분도 주석이다.

 

 

한 줄 주석은 다음과 같은 경우에 유용하다.

• 코드의 목적 설명: 특정 코드 블록이 무엇을 하는지 간략하게 설명할 때.
• 복잡한 로직 설명: 이해하기 어려운 코드 부분에 대한 상세 설명을 덧붙일 때.
• 임시 코드 비활성화: 테스트를 위해 특정 코드를 일시적으로 실행하지 않게 할 때.

 

1.2. 여러 줄 주석: """ (따옴표 세 개) 사용

여러 줄에 걸쳐 긴 설명을 작성해야 할 때 사용한다. 일반적으로 함수나 클래스의 목적, 매개변수, 반환 값 등을 설명하는 독스트링(Docstring)으로 많이 활용된다. 독스트링은 특별한 주석으로, 코드에 대한 공식 문서처럼 사용될 수 있다.

"""
이것은 여러 줄 주석입니다.
함수나 파일의 목적을 설명할 때 주로 사용합니다.
여러 줄로 설명을 작성할 수 있어 매우 편리합니다.
"""
def add_numbers(a, b):
    """
    두 숫자를 더하여 그 결과를 반환하는 함수입니다.

    매개변수:
    a (int): 첫 번째 숫자
    b (int): 두 번째 숫자

    반환 값:
    int: 두 숫자의 합
    """
    return a + b

print(add_numbers(3, 5)) # 출력: 8

 

 

여러 줄 주석은 다음과 같은 경우에 유용하다.

• 독스트링: 함수, 클래스, 모듈의 자세한 설명. (추후 자동 문서화 도구로 추출될 수 있다.)
• 긴 설명: 코드 파일의 저작권 정보, 라이선스, 전체적인 파일 설명 등 여러 줄이 필요한 설명.

---

 

2. 주석 작성 가이드라인: 좋은 주석이란?

단순히 주석을 다는 것만큼 중요한 것은 '어떤 주석을 달 것인가'이다. 좋은 주석은 코드를 더욱 명확하게 만들고, 불필요한 주석은 오히려 코드를 지저분하게 만들 수 있다.

 

• "왜(Why)"에 집중하라: 코드가 "무엇(What)"을 하는지는 코드 자체로 설명되는 경우가 많다. 주석은 코드가 "왜(Why)" 그렇게 작동하는지, 특정 결정을 내린 이유가 무엇인지에 초점을 맞추는 것이 좋다.
• 간결하고 명확하게: 장황한 설명보다는 핵심을 짚는 짧고 명확한 주석이 더 효과적이다.
• 코드와 동기화: 코드를 수정했다면, 관련 주석도 반드시 업데이트해야 한다. 오래된 주석은 잘못된 정보를 제공하여 혼란을 줄 수 있다.
• 불필요한 주석 피하기: 너무나 당연한 내용을 주석으로 달 필요는 없다. (예: x = x + 1 # x에 1을 더한다.)
• 영어 사용 (선택 사항): 오픈소스 프로젝트나 다국적 팀에서는 주석을 영어로 작성하는 것이 일반적이다.