주석(Comment)과 코드 가독성: 소통하는 코드의 비밀

1. 서론: 코드는 기계뿐 아니라 사람을 위한 것

프로그래밍은 컴퓨터에게 명령을 내리는 행위이지만, 동시에 다른 개발자(그리고 미래의 자신)와 소통하는 행위이기도 합니다. 여러분이 작성한 코드는 컴퓨터가 이해하고 실행할 수 있어야 할 뿐만 아니라, 사람이 읽고 이해하기 쉬워야 합니다. 아무리 완벽하게 동작하는 코드라도 그 의도를 파악하기 어렵다면, 유지보수나 협업 과정에서 큰 어려움을 겪게 됩니다. 이때 코드의 가독성을 높이고 그 의도를 명확히 전달하는 데 필수적인 도구가 바로 ‘주석(Comment)’입니다. 주석은 파이썬 인터프리터가 무시하는 부분으로, 코드의 동작에는 영향을 미치지 않지만, 코드를 읽는 사람에게는 매우 중요한 정보를 제공합니다. 이 챕터에서는 주석의 중요성과 파이썬에서 주석을 작성하는 다양한 방법, 그리고 좋은 주석을 작성하기 위한 원칙에 대해 깊이 있게 알아보겠습니다. 주석을 효과적으로 활용하는 것은 여러분의 코드를 더욱 전문적이고 협업에 용이하게 만들 것입니다.

2. 주석(Comment)이란 무엇인가?

주석은 프로그램 코드 내에 작성되지만, 파이썬 인터프리터가 코드를 실행할 때 무시하는 텍스트 부분입니다. 즉, 주석은 프로그램의 동작에 아무런 영향을 미치지 않습니다. 주석의 주된 목적은 다음과 같습니다.

• 코드 설명: 복잡한 로직이나 특정 코드 블록의 목적을 설명하여 다른 개발자(또는 미래의 자신)가 코드를 쉽게 이해할 수 있도록 돕습니다.
• 코드의 의도 전달: 코드가 ‘무엇을’ 하는지뿐만 아니라, ‘왜’ 그렇게 작성되었는지에 대한 배경이나 의도를 설명합니다.
• 임시 코드 비활성화: 특정 코드 라인을 일시적으로 실행되지 않도록 만들 때 사용합니다. (디버깅 목적 등)
• 저작권 정보, 작성자, 날짜 등 메타데이터 기록: 코드에 대한 부가적인 정보를 남깁니다.

3. 파이썬에서 주석 작성하는 방법

파이썬은 크게 두 가지 방법으로 주석을 작성할 수 있습니다.

3.1. 한 줄 주석 (#)

가장 일반적인 주석 방식입니다. # 기호 뒤에 오는 모든 텍스트는 해당 줄의 끝까지 주석으로 처리됩니다.

# 이것은 한 줄 주석입니다.

print("Hello, World!") # 이 코드는 화면에 메시지를 출력합니다.

# 변수 선언
name = "Alice" # 사용자의 이름을 저장하는 변수

• #은 코드의 시작 부분에 올 수도 있고, 코드 라인 뒤에 올 수도 있습니다.
• 코드 라인 뒤에 오는 주석은 해당 코드에 대한 간략한 설명을 추가할 때 유용합니다.

3.2. 여러 줄 주석 (독스트링 또는 삼중 따옴표)

파이썬에는 공식적으로 여러 줄 주석을 위한 별도의 문법은 없습니다. 하지만 일반적으로 여러 줄의 문자열 리터럴(삼중 따옴표 """...""" 또는 '''...''')을 사용하여 여러 줄 주석처럼 활용합니다. 특히 함수, 클래스, 모듈의 정의 바로 아래에 오는 삼중 따옴표 문자열은 ‘독스트링(Docstring)’이라고 불리며, 특별한 의미를 가집니다.

"""이것은 여러 줄 주석처럼 사용될 수 있습니다.
보통 코드 블록의 시작 부분이나 파일의 맨 위에
전반적인 설명을 작성할 때 사용됩니다.
"""

'''
이것도 여러 줄 주석처럼 사용될 수 있습니다.
작은따옴표 세 개를 사용해도 동일하게 동작합니다.
'''

def calculate_sum(a, b):
    """두 숫자의 합을 계산하여 반환하는 함수입니다.

    Args:
        a (int): 첫 번째 숫자
        b (int): 두 번째 숫자

    Returns:
        int: 두 숫자의 합
    """
    return a + b

# 독스트링은 help() 함수나 IDE의 도움말 기능을 통해 접근할 수 있습니다.
print(help(calculate_sum))

• 일반적인 여러 줄 주석: 코드의 특정 섹션이나 복잡한 알고리즘에 대한 자세한 설명을 제공할 때 사용합니다.
• 독스트링 (Docstring): 함수, 클래스, 모듈의 목적, 사용법, 매개변수, 반환 값 등을 설명하는 데 사용됩니다. 독스트링은 파이썬의 내장 help() 함수나 IDE의 자동 완성/도움말 기능을 통해 접근할 수 있어, 코드의 문서화에 매우 중요한 역할을 합니다.

4. 좋은 주석을 작성하는 원칙

주석은 많다고 해서 무조건 좋은 것이 아닙니다. 오히려 불필요하거나 잘못된 주석은 코드의 가독성을 해치고 혼란을 야기할 수 있습니다. 다음은 좋은 주석을 작성하기 위한 몇 가지 원칙입니다.

4.1. 코드가 ‘무엇을’ 하는지보다 ‘왜’ 하는지를 설명하라

코드가 너무 자명한데도 주석을 다는 것은 불필요합니다. 예를 들어 x = x + 1 # x에 1을 더한다와 같은 주석은 의미가 없습니다. 대신, 코드가 왜 그렇게 작성되었는지, 어떤 의도를 가지고 있는지, 어떤 문제에 대한 해결책인지 등 코드만으로는 알기 어려운 배경 지식을 설명하는 데 집중해야 합니다.

• 나쁜 예: total = price * quantity # 가격과 수량을 곱하여 총액을 계산
• 좋은 예: total = price * quantity # 세금 계산을 위해 총액을 먼저 산출

4.2. 최신 상태를 유지하라

코드가 변경되었는데 주석이 업데이트되지 않으면, 주석은 오히려 잘못된 정보를 제공하여 혼란을 야기합니다. 오래된 주석은 없는 것보다 못할 수 있습니다. 코드를 수정할 때는 관련 주석도 함께 업데이트하는 습관을 들여야 합니다.

4.3. 간결하고 명확하게 작성하라

주석은 핵심 내용을 간결하고 명확하게 전달해야 합니다. 장황하거나 모호한 표현은 피하고, 필요한 정보만을 정확하게 기술합니다.

4.4. 코드의 중복을 피하라

코드가 이미 충분히 설명적이라면 주석을 달 필요가 없습니다. 변수 이름이나 함수 이름만으로도 충분히 의미를 전달할 수 있도록 코드를 잘 작성하는 것이 가장 좋은 주석입니다.

4.5. 복잡한 로직이나 예외적인 상황을 설명하라

특히 복잡한 알고리즘, 특정 조건에 대한 예외 처리, 또는 예상치 못한 동작이 발생할 수 있는 부분에는 주석을 달아 설명하는 것이 매우 유용합니다. 이는 디버깅이나 유지보수 시 시간을 절약해 줍니다.

4.6. PEP 8 스타일 가이드 준수

파이썬 코딩 스타일 가이드인 PEP 8은 주석 작성에 대한 몇 가지 권장 사항을 제시합니다.

• # 뒤에는 공백을 하나 둡니다. (예: # 이것은 주석입니다.)
• 코드 라인 뒤에 오는 주석은 코드와 # 사이에 두 개 이상의 공백을 둡니다. (예: x = 10 # 변수 x에 10 할당)
• 독스트링은 삼중 따옴표로 감싸고, 첫 줄은 요약, 그 다음 줄부터 상세 설명을 작성합니다.

5. 주석의 중요성: 협업과 유지보수

주석은 단순히 코드를 설명하는 것을 넘어, 소프트웨어 개발의 핵심적인 두 가지 측면인 ‘협업’과 ‘유지보수’에 지대한 영향을 미칩니다.

5.1. 협업의 윤활유

소프트웨어 개발은 대부분 팀 단위로 이루어집니다. 여러 개발자가 하나의 프로젝트에 참여할 때, 각자가 작성한 코드를 다른 팀원들이 쉽게 이해할 수 있어야 합니다. 잘 작성된 주석은 코드의 의도를 명확히 전달하여 팀원 간의 소통 비용을 줄이고, 코드 리뷰 과정을 효율적으로 만듭니다. 새로운 팀원이 프로젝트에 합류했을 때도 주석은 코드베이스를 빠르게 파악하는 데 큰 도움을 줍니다.

5.2. 미래를 위한 투자

오늘 작성한 코드는 내일의 여러분에게도 낯설게 느껴질 수 있습니다. 몇 주, 몇 달, 심지어 몇 년 후에 다시 코드를 보게 될 때, 당시의 생각이나 의도를 기억하기란 쉽지 않습니다. 이때 잘 작성된 주석은 여러분이 과거의 코드를 다시 이해하고 수정하는 데 귀중한 가이드 역할을 합니다. 주석은 미래의 자신을 위한 투자라고 할 수 있습니다.

6. 결론: 주석, 좋은 개발자의 필수 역량

이 챕터를 통해 여러분은 파이썬에서 주석을 작성하는 다양한 방법과 좋은 주석을 작성하기 위한 원칙들을 학습했습니다. 주석은 코드의 가독성을 높이고, 의도를 명확히 전달하며, 협업과 유지보수를 용이하게 하는 매우 중요한 도구입니다. 단순히 코드를 설명하는 것을 넘어, 코드가 ‘왜’ 그렇게 작성되었는지에 대한 배경과 의도를 담는 것이 좋은 주석의 핵심입니다.

이제 여러분은 파이썬의 기본적인 자료형과 연산자, 그리고 코드의 가독성을 높이는 주석까지 다룰 수 있게 되었습니다. 주석을 작성하는 습관을 들이고, 항상 코드를 읽는 사람의 입장에서 생각하며 의미 있는 주석을 달도록 노력하세요. 이는 여러분의 코딩 실력뿐만 아니라, 개발자로서의 전문성을 한 단계 더 높여줄 것입니다.

다음 챕터에서는 사용자로부터 데이터를 입력받고, 그 결과를 화면에 출력하는 방법에 대해 자세히 알아보겠습니다. input() 함수와 print() 함수는 사용자와 프로그램이 상호작용하는 가장 기본적인 방법이므로, 이들을 이해하는 것은 여러분의 프로그램을 더욱 풍부하게 만들 것입니다.