파이썬 주석: 한 줄 주석, 여러 줄 주석, Docstring

주석은 사람을 위한 거예요

파이썬은 주석을 무시합니다. 트릭이랄 것도 이게 전부예요. 여러분이 주석으로 표시한 건 인터프리터에게는 보이지 않아요 — 오로지 코드를 읽을 사람을 위한 거죠. 그리고 그 사람은 보통 여섯 달 뒤의 자기 자신이에요. "과거의 내가 대체 무슨 생각을 한 거지?" 하고 있을 미래의 나 말이에요.

그런데 코드가 봐도 뻔한 일을 다시 한 번 풀어쓰는 주석은 굳이 달 값어치가 없어요. 가장 좋은 주석은 _왜_를 설명합니다 — 어떤 제약 때문에, 어떤 우회책을 쓴 이유, 코드만 봐서는 알 수 없는 어떤 결정 같은 것들이요. 무엇을 하고 있는지는 이미 코드가 말해주고 있어요.

#을 쓰는 한 줄 주석

기본 형태는 # 뒤에 메모를 붙이는 거예요:

줄 끝에 짧은 주석을 덧붙일 수도 있어요. 관례상 # 앞에 공백을 최소 두 칸 띄웁니다:

파이썬은 문자열 바깥에서 #을 만나면 그 뒤부터 줄 끝까지를 주석으로 취급해요. '문자열 바깥'이라는 점이 중요해요. 따옴표 안에 있는 #은 그냥 문자예요.

문자열 안의 #section-2는 URL의 일부예요. 파이썬은 문자열이 닫힌 뒤에 등장한 #부터만 "주석 모드"로 들어갑니다.

여러 줄 주석 처리하기

파이썬에는 /* */ 같은 블록 주석이 없어요. 여러 줄을 건너뛰려면 각 줄 앞에 #을 붙이세요:

이 #들을 손으로 하나하나 찍는 일은 거의 없어요. 웬만한 에디터에는 선택된 모든 줄에 #을 붙이고 떼주는 "토글 주석" 단축키가 있거든요:

• VS Code: Cmd + / (macOS) 또는 Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / 또는 Ctrl + /
• Vim: 플러그인에 따라 달라요. vim-commentary는 한 줄에 gcc, 선택 영역에 gc로 바인딩돼 있습니다.

한 번만 단축키를 익혀두면, "이 블록 잠깐 주석 처리하고 뭐 좀 해봐야지"가 키 한 번 누르는 일이 됩니다.

삼중 따옴표 문자열 트릭 (과 그게 진짜 주석이 아닌 이유)

이런 코드를 가끔 볼 거예요:

엄밀히 말하면 이건 그냥 버려지는 문자열 표현식이에요. 파이썬이 파싱해서, 평가해서, 결과를 버립니다. 주석처럼 _동작_하지만 주석은 아니에요. 스타일적으로 이게 좋은 선택이 되는 곳은 딱 한 군데뿐이에요: docstring.

Docstring: 삼중 따옴표가 제자리를 찾는 곳

docstring은 함수, 클래스, 모듈의 맨 첫 문장 자리에 놓는 삼중 따옴표 문자열이에요. 파이썬은 이걸 문서로 인식하고, 실행 시점에 help() 함수나 __doc__ 속성을 통해 접근할 수 있게 해줍니다:

docstring이 좋은 이유는 두 가지예요:

1. IDE, help(), 문서 생성 도구 같은 것들이 이걸 자동으로 읽어줍니다. 함수 위에 단 주석은 이런 혜택을 아예 못 받아요.
2. 호출하는 자리에서 함수 설명을 바로 볼 수 있어요 — 누군가 에디터에서 discount(...) 위에 마우스를 올리면, docstring이 툴팁으로 뜹니다.

docstring 내용 구성에는 관례(PEP 257)가 있어요. 첫 줄에 한 줄 요약, 한 줄 띄우고, 필요하면 더 긴 설명. 첫날부터 정확한 형식에 스트레스받지 마세요 — 평범한 한 줄짜리라도 docstring이 아예 없는 것보다는 훨씬 나아요.

진짜 좋은 주석이 말하는 것

나중에 속 썩는 일을 많이 줄여주는 가이드라인 몇 개:

• 무엇보다 _왜_를 설명하세요. # 사용자 반복 은 소음이에요. # 503 응답에서는 재시도 — 배포 중간에 Redis가 가끔 죽음 은 금이에요.
• 코드를 고치면 주석도 같이 고치세요. 틀린 주석은 없는 주석보다 나빠요. 오래돼 내용이 맞지 않는 주석은 앞으로 읽을 사람들을 적극적으로 오도합니다.
• 코드를 주석 처리한 채 방치하지 마세요. 필요 없으면 지우세요. 버전 관리가 기억해 줍니다. 주석 처리된 블록이 여기저기 박힌 파일은 빠르게 신뢰를 잃어요.
• 뻔한 건 굳이 쓰지 마세요. x = x + 1 # x 증가 는 아무것도 보태지 않아요.

요약

주석은 쓰는 비용도 싸고, 안 써도 비용이 안 들어요. 읽을 사람이 고마워할 메모 — 어떤 미묘한 동작의 이유, 이슈 링크, 예외 상황 경고 같은 것 — 가 있을 때 꺼내 쓰세요. 함수나 클래스를 정의할 때는 docstring을 쓰고요. 그 외에는 명확한 이름과 작은 함수가 알아서 말하게 두세요.

이제 파이썬 파일을 읽고 쓰는 데 필요한 건 다 갖췄어요. 다음 챕터부터는 언어가 실제로 뭔가를 하기 시작합니다: 변수, 자료형, 그리고 파이썬이 담을 수 있는 값들이요.