[클린코드 파이썬] 11장: 주석과 타입 힌트

프로그램은 반드시 사람이 읽을 수 있게 작성되는 것이 우선이며, 부차적으로 컴퓨터가 실행할 수 있어야 한다.

 

소스 코드에 직접 기입하는 주석comment은 컴퓨터가 무시하는 간단한 설명이다.

독스트링docstring은 함수, 메소드, 모듈에 대한 파이썬 문서 형식이다.

타입 힌트type hint는 변수, 파라미터, 반환값의 데이터 타입을 명세하기 위해 파이썬 소스 코드에 추가할 수 있는 지시자directive다.

 

 

주석

단일행 주석은 #, 다중행 주석은 """를 사용한다.

# 이것은 단일행 주석이다.
"""이것은
다중행 문자열로 구성되어
다중행 주석으로 사용된다 """

 

 

주석 스타일

# 아래 줄 코드에 대한 주석부는 여기 넣는다
someCode()

# 이 부분은 여러 개의 단일 행 주석을
# 기호를 이용해 연속으로 배치해 여러 행에 길게 걸치게 만든 블록 주석이다
#
# 이런 형태를 블록 주석이라 부른다

if someCondition:
    # 또 다른 코드에 대한 주석부는 여기에 넣는다
    someOtherCode()  # 이 형태는 인라인 주석이다

 

단일행 주석에서는 # 기호 뒤에 반드시 공백을 둬야 한다.

 

 

인라인 주석은 변수에 대해 목적을 설명하거나 그 밖의 맥락을 제공하느 ㄴ것이다.

TOTAL_DISKS = 5  # 원판이 많을수록 퍼즐은 어려워진다

인라인 주석으로 변수의 데이터 타입을 명세해서는 안 된다. 할당문에서 명백히 드러나기 때문이다.

 

 

설명 주석

일반적으로 주석은 코드가 무엇을 어떻게 하는지보다 해당 코드가 그와 같이 작성된 이유를 설명해줘야 한다.

예를 들어 다음은 코드에서 수행하는 작업을 설명하는 바람에 쓸모없는 주석이 되어버린 예다.

currentWeekWages *= 1.5  # 현재 주급의 1.5배

 

오히려 주석을 아예 제거한다면 코드가 더 단순해진다. 다음이 훨씬 더 나은 주석일 테다.

currentWeekWages *= 1.5  # 초과 근무 시간 반영

 

 

요약 주석

요약 주석summary comment은 보통 코드 문단의 시작부분의 첫줄을 차지한다. 한 줄의 코드를 설명하는 단일행 주석과 달리, 요약 주석은 더 높은 추상화 수준에서 코드가 무엇을 하는지를 설명한다.

# 다른 플레이어에게 차례를 넘김:
if playerTurn == PLAYER_X:
    playerTuen = PLAYER_O
elif playerTurn == PLAYER_O:
    playerTuen = PLAYER_X

프로그램 곳곳에 이런 요약 주석이 박혀 있으면 빠르게 훑어보기가 훨씬 쉬워진다.

 

 

 

경험 지식을 담은 주석

전체 개발 과정에서 그래프 라이브러리가 작동하는 방식, 그리고 가능한 범위와 한계가 무엇인지에 대한 세부 사항을 많이 배웠다. 그 후 나는 몇 시간을 들여 이 세부사항들을 소스 코드에 한 페이지 길이의 주석으로 작성했다. 내가 작성하는 문서가 다른 사람들이 글자 그대로 몇 주를 허비하는 수고를 줄여줄 것임을 알았기 때문이다.

 

 

코드태그와 TODO 주석

TODO와 같은 전체 대문자 레이블 뒤에 간단한 설명이 뒤따르는 형태의 주석이다.

_chargeIonFluxStream()  # TODO: 왜 매주 화요일이면 장애가 발생하는지, 원인 파악 필요함

 

 

매직 주석과 소스 파일 인코딩

소스 코드 상단에 다음과 같은 행이 있는 .py 소스 파일을 본 적이 있을 것이다.

#!/usr/bin/env python3'
# -*- coding: utf-8 -*-

항상 파일의 맨 위에 표시되는 이 매직 주석magic comment은 인터프리터 또는 인코딩 정보를 제공한다.

 

 

 

독스트링

독스트링docstring은 코듈의 .py 소스 코드 파일 맨 위에 등장하거나 class나 def 문 뒤에 바로 이어지는 다중행 주석이다. 독스트링은 정의된 모듈, 클래스, 함수, 메소드 등에 대한 문서를 제공한다.

 

 

 

타입 힌트

파이썬의 타입 힌트type hint는 정적 타입을 선택적으로 제공한다.

def describeNumber(number: int) -> str:
    if number % 2 == 1:
    	return 'An odd number. '
    elif number == 42:
    	return 'The answer. '
    else:
    	return 'Yes, that is a number. '

myLuckyNumber: int = 42
print(describeNumber(myLuckyNumber))

파라미터나 변수의 경우 타입 힌트는 콜론을 사용해 이름과 타입을 구분하고, 반환값은 화살표(->)를 사용해 def 문의 닫힘 괄호와 타입을 구분한다. describeNumber() 함수의 타입 힌트는 숫자 파라미터에 대해 정수(int) 값을 취하고 문자열(str) 값을 반환한다는 것을 보여준다.

 

타입 힌트를 사용한다고 해서, 프로그램의 모든 데이터에 적용할 필요는 없다.

 

 

타입 힌트를 다중 타입으로 설정하기

Union 클래스명 뒤 대괄호 안에 타입의 범위를 지정한다.

from typing import Union
spam: Union[int, str, float] = 42
spam = 'hello'
spam = 3.14

 

None 타입을 나타내려면 typing 모듈에서 Optional을 임포트해서 Optional[str]을 사용한다.

from typing import Optional
lastName: Optional[str] = None
lastName = 'Sweigart'

 

Any 타입 힌트를 사용하면 변수나 파라미터, 반환값이 임의의 데이터 타입이 되도록 지정할 수 있다.

from typing import Any
import datetime
spam: Any = 42
spam = datetime.date.today()
spam = True