공식 문서 읽는 법과 좋은 질문하는 법
블로그와 AI의 답보다 먼저 볼 곳은 공식 문서예요. 문서의 네 가지 종류와 읽는 순서, 함수 서명의 / 와 * 같은 표기 읽기, 문서를 읽어야만 알 수 있는 동작(split의 두 얼굴, round(2.5)가 2인 이유), 내 버전에 맞는 문서와 지원 중단 경고 확인을 실제 코드로 익혀요. 그래도 막혔을 때 사람과 AI에게 답을 빨리 얻는 질문의 구조와 예절까지 정리해요.
막히면 검색창에 오류 메시지를 넣고, 맨 위에 나온 블로그 글을 따라 하고, 안 되면 다음 글로 넘어가기 쉬워요. 운이 좋으면 풀리지만, 몇 년 전 버전 기준이거나 글쓴이도 잘 모르고 쓴 글이면 시간만 버려요. AI의 답도 그럴듯하지만 틀릴 때가 있어요. 그래서 실력 있는 개발자들은 공식 문서부터 봐요. 만든 사람들이 직접 쓴, 가장 정확하고 최신인 설명이니까요.
문서의 네 가지 얼굴
잘 만든 문서는 목적에 따라 네 종류로 나뉘어 있어요. 소프트웨어 문서를 쓰는 사람들 사이에 널리 퍼진 디아탁시스(Diátaxis)라는 정리 방식이에요.
| 종류 | 목적 | 이럴 때 읽어요 |
|---|---|---|
| 튜토리얼 | 따라 하며 배우기 | 처음 써 볼 때 |
| 방법 안내(How-to) | 특정 문제 풀기 | "CSV 파일은 어떻게 읽지?" |
| 레퍼런스 | 모든 기능의 정확한 설명 | 함수의 매개변수, 반환값, 예외를 확인할 때 |
| 설명 | 왜 이렇게 만들었는지, 원리 | 깊이 이해하고 싶을 때 |
처음 배우는 라이브러리라면 튜토리얼을 한 번 끝까지 따라 해요. 전체 그림이 생기면 그다음부터는 필요할 때 레퍼런스에서 찾아 쓰면 돼요. 많은 사람이 튜토리얼을 건너뛰고 레퍼런스부터 보다가 길을 잃어요.
레퍼런스 읽기: 함수 서명
레퍼런스의 핵심은 함수의 서명(시그니처)이에요. 어떤 입력을 어떻게 받는지 한 줄로 보여 줘요. 파이썬에서는 inspect로 직접 볼 수도 있어요.
import inspect
print(inspect.signature(sorted))
print(sorted([3, 1, 2], reverse=True))
try:
sorted([3, 1, 2], True)
except TypeError as e:
print("TypeError:", e)
(iterable, /, *, key=None, reverse=False)
[3, 2, 1]
TypeError: sorted expected 1 argument, got 2
처음 보면 낯선 기호가 있어요.
/: 그 앞의 매개변수(iterable)는 위치로만 줄 수 있어요.sorted(iterable=[3, 1, 2])처럼 이름을 붙여 쓸 수 없다는 뜻이에요.*: 그 뒤의 매개변수(key,reverse)는 이름으로만 줄 수 있어요. 그래서sorted([3, 1, 2], True)가 오류가 났어요.reverse=True처럼 써야 해요.key=None: 기본값이 있는 매개변수예요. 안 주면None이에요.
이 표기를 알면 오류 메시지가 바로 이해돼요. "인자를 1개 받는데 2개를 줬다"는 건, 두 번째 값을 위치로 줬기 때문이에요. 레퍼런스에서는 서명 다음에 각 매개변수의 뜻, 반환값, 일으킬 수 있는 예외, 예제를 차례로 확인해요.
문서를 읽어야만 아는 것들
어떤 동작은 추측으로는 절대 알 수 없고, 문서에만 적혀 있어요.
print(inspect.signature(str.split))
print("a,b,,c".split(","), "a b c".split(), "a b c".split(" "))
print(round(2.5), round(3.5), round(0.125, 2))
(self, /, sep=None, maxsplit=-1)
['a', 'b', '', 'c'] ['a', 'b', 'c'] ['a', 'b', '', 'c']
2 4 0.12
split()의 두 얼굴: 나눌 기준(sep)을 주면 그 글자마다 정확히 나눠서, 연속된 쉼표 사이에 빈 문자열이 생겨요. 그런데 기준을 안 주면 공백이 몇 개든 하나로 보고, 앞뒤 공백도 무시해요. 같은 공백인데split()과split(" ")의 결과가 달라요. 파이썬 문서에 정확히 이렇게 적혀 있어요.round(2.5)가 2인 이유: 학교에서 배운 반올림이라면 3이어야 하죠. 파이썬의round는 딱 중간일 때 짝수 쪽으로 보내요. 그래서 2.5는 2, 3.5는 4예요. 많이 더할 때 한쪽으로 쏠리는 오차를 줄이는 방식이에요. 이것도 문서에 적혀 있어요.
이런 걸 모르고 쓰면 버그가 생겨도 원인을 못 찾아요. 처음 쓰는 함수는 레퍼런스를 한 번은 끝까지 읽어 보는 습관이 좋아요.
내 버전의 문서인가
라이브러리는 버전마다 기능이 생기고, 바뀌고, 사라져요. 문서와 내 버전이 다르면 문서대로 해도 안 돼요.
- 내 버전 확인: 파이썬은
python --version, 라이브러리는pip show 이름이나 코드에서importlib.metadata.version("이름")으로 확인해요. - 문서의 버전 고르기: 공식 문서 사이트에는 보통 버전을 고르는 메뉴가 있어요. 검색으로 들어간 페이지가 옛 버전 문서인 경우가 많으니 꼭 확인해요.
- 변경 기록 읽기: 버전을 올릴 때는 변경 기록(체인지로그, 릴리스 노트)과 이전 안내서(마이그레이션 가이드)를 읽어요. 무엇이 바뀌어서 내 코드가 깨질 수 있는지 적혀 있어요.
- 지원 중단 경고에 귀 기울이기: 곧 없어질 기능을 쓰면 파이썬이 경고를 보여 줘요.
import datetime
import warnings
with warnings.catch_warnings(record=True) as caught:
warnings.simplefilter("always")
datetime.datetime.utcnow() # 옛날 방식
print(caught[0].category.__name__)
print(caught[0].message)
print(datetime.datetime.now(datetime.UTC).tzinfo) # 경고가 알려 준 새 방식은 시간대를 품고 있어요
DeprecationWarning
datetime.datetime.utcnow() is deprecated and scheduled for removal in a future version. Use timezone-aware objects to represent datetimes in UTC: datetime.datetime.now(datetime.UTC).
UTC
경고에는 무엇이 문제인지와 무엇으로 바꾸면 되는지까지 적혀 있어요(파이썬 3.12부터 나오는 경고예요). 경고는 오류가 아니라서 그냥 지나치기 쉽지만, 다음 버전에서 진짜 오류가 돼요. 보이면 바로 고치는 게 가장 싸요.
문서에 없을 때
- 예제와 시험 코드: 저장소의
examples폴더나 시험 코드(tests)는 실제로 돌아가는 사용법 모음이에요. - 소스 코드: 문서가 부족하면 함수의 코드를 직접 읽어요. 파이썬은 편집기에서 함수 이름을 눌러 정의로 이동할 수 있어요. 처음엔 어렵지만 가장 확실한 답이에요.
- 이슈 게시판: 깃허브 저장소의 이슈(Issues)를 검색하면 같은 문제를 겪은 사람과 개발자의 답이 있는 경우가 많아요. 해결됐는지, 어느 버전에서 고쳐졌는지도 보여요.
검색을 잘하는 법
- 오류 메시지의 핵심을 그대로: 내 파일 경로나 변수 이름처럼 나만의 부분은 빼고, 오류 종류와 메시지를 큰따옴표로 묶어 검색해요.
- 버전을 함께: "pandas 2 read_csv encoding"처럼 버전을 넣어요.
- 날짜 확인: 답이 몇 년 전 것인지 봐요. 옛 버전의 해결책일 수 있어요.
- 공식 출처 먼저: 검색 결과에서 공식 문서, 공식 저장소의 이슈를 블로그보다 먼저 봐요.
- 이해하고 쓰기: 찾은 코드를 붙여 넣기 전에 각 줄이 무엇을 하는지 이해해요. 특히 남이 준 명령어를 관리자 권한으로 실행하는 건 위험해요.
좋은 질문하기
혼자 30분에서 1시간쯤 시도했는데도 막히면, 물어보는 게 시간을 아끼는 길이에요. 그런데 질문을 어떻게 하느냐에 따라 답이 5분 만에 오기도 하고, 영영 안 오기도 해요. 답하는 사람은 내 화면을 볼 수 없다는 걸 기억하세요.
좋은 질문에는 이런 것들이 들어가요.
- 목표: 무엇을 하려고 하나요? (가끔은 방법 자체가 잘못된 경우도 있어서, 목표를 알면 더 나은 길을 알려 줄 수 있어요.)
- 현상: 무엇을 했고, 무엇을 기대했고, 실제로는 무엇이 일어났나요?
- 오류 전문: 오류 메시지와 트레이스백을 글자로 붙여요. 사진은 검색도 복사도 안 돼요.
- 가장 작은 재현 코드: 디버깅 강의에서 만든, 문제가 그대로 나는 가장 짧은 코드예요. 이걸 만들다 스스로 답을 찾는 경우도 많아요.
- 환경: 운영체제, 언어와 라이브러리 버전이에요.
- 해 본 것: 무엇을 시도했고 결과가 어땠는지 적어요. 같은 답을 두 번 듣지 않게요.
제목도 중요해요. "도와주세요 급해요"보다 "pandas read_csv에서 한글이 깨져요 (윈도, pandas 2.2)"가 훨씬 빨리 답을 받아요.
제목: pandas read_csv로 읽은 한글이 깨져요 (윈도 11, pandas 2.2)
하고 싶은 것: 엑셀에서 저장한 CSV 파일을 읽어 합계를 내고 싶어요.
현상: 숫자는 잘 읽히는데, 이름 열의 한글이 이상한 글자로 나와요.
코드:
import pandas as pd
df = pd.read_csv("명단.csv")
print(df.head())
출력: (깨진 글자 그대로 붙임)
해 본 것: encoding="utf-8"을 넣었더니 UnicodeDecodeError가 났어요.
환경: 윈도 11, 파이썬 3.12, pandas 2.2.2
이 질문을 받은 사람은 곧바로 "엑셀이 CSV를 cp949로 저장했을 수 있으니 encoding="cp949"로 읽어 보세요"라고 답할 수 있어요. 필요한 정보가 다 있으니까요.
질문의 예절
- 답을 받으면 해결됐는지 알려 주고 고마움을 표현해요.
- 스스로 해결했다면 해결 방법을 남겨요. 나중에 같은 문제를 검색할 누군가에게 큰 도움이 돼요.
- 여러 곳에 같은 질문을 올렸다면 서로 알려 줘요. 답하는 사람들의 시간도 소중해요.
- 비밀번호, API 키, 개인 정보가 코드나 로그에 섞여 있지 않은지 올리기 전에 꼭 확인해요.
AI에게 묻기
AI에게 물을 때도 원칙은 같아요. 목표, 현상, 오류 전문, 코드, 환경을 주면 답이 훨씬 정확해져요(LLM 트랙의 프롬프트 강의). 다만 두 가지를 더 기억해요.
- 확인하기: AI는 없는 함수나 옛 버전의 사용법을 자신 있게 말할 때가 있어요. 답에 나온 함수와 매개변수는 공식 문서에서 확인하고, 직접 실행해 봐요.
- 비밀 지키기: 회사 코드나 개인 정보를 붙여 넣어도 되는지, 쓰는 서비스의 데이터 정책과 회사 규칙을 먼저 확인해요.
실습
- 자주 쓰는 내장 함수 하나(
print,open,max등)를 골라inspect.signature로 서명을 보고, 파이썬 공식 문서의 설명과 맞춰 보세요./나*가 있나요? " hello world ".split()과" hello world ".split(" ")의 결과를 예상한 뒤 실행해 보세요.round(0.5),round(1.5),round(2.675, 2)의 결과를 예상하고 확인해 보세요. 마지막 결과가 예상과 다르다면, 디버깅 강의의 부동소수점 이야기와 연결해 보세요.- 지금 쓰는 라이브러리 하나의 버전을 확인하고, 공식 문서에서 그 버전의 변경 기록을 찾아 읽어 보세요.
- 최근에 막혔던 문제 하나로, 위의 여섯 가지가 들어간 질문을 써 보세요. 쓰다가 답이 보였나요?
자주 하는 실수
- 튜토리얼 없이 레퍼런스부터 보기. 전체 그림 없이 세부에서 길을 잃어요.
- 문서 버전 확인 안 하기. 내 버전에 없는 기능을 찾느라 시간을 써요.
- 경고 무시하기. 다음 버전에서 오류가 돼요.
- 오류를 사진으로 보내기. 글자로 붙여야 검색하고 복사할 수 있어요.
- "안 돼요"만 쓰기. 무엇을 했고 무엇이 일어났는지 구체적으로 써요.
- 이해하지 못한 코드 붙여 넣기. 특히 남이 준 명령어를 관리자 권한으로 실행하지 않아요.
점검 문제
- 문서의 네 종류는 무엇이고, 처음 배우는 라이브러리라면 어느 것부터 읽나요?
- 서명
(iterable, /, *, key=None, reverse=False)에서/와*의 뜻은? "a b c".split()과"a b c".split(" ")의 결과가 다른 이유는?- 파이썬에서
round(2.5)가 2인 이유는? - 지원 중단 경고를 보면 어떻게 해야 하나요?
- 좋은 질문에 들어가야 할 것 여섯 가지는?
- AI가 알려 준 코드를 쓰기 전에 해야 할 일은?
정답
- 튜토리얼, 방법 안내, 레퍼런스, 설명이에요. 처음이라면 튜토리얼을 끝까지 따라 해요.
/앞의 매개변수는 위치로만,*뒤의 매개변수는 이름으로만 줄 수 있어요.- 나눌 기준을 안 주면 연속된 공백을 하나로 보고 앞뒤 공백도 무시하지만, 기준으로 공백 하나를 주면 공백마다 정확히 나눠서 빈 문자열이 생기기 때문이에요.
- 딱 중간인 값을 짝수 쪽으로 보내는 방식이라서예요. 많이 더할 때 오차가 한쪽으로 쏠리는 걸 줄여요.
- 경고가 알려 주는 새 방식으로 바로 고쳐요. 다음 버전에서는 오류가 될 수 있어요.
- 목표, 현상(한 일, 기대, 실제), 오류 전문, 가장 작은 재현 코드, 환경(버전), 해 본 것이에요.
- 나온 함수와 매개변수를 공식 문서에서 확인하고, 직접 실행해서 동작을 확인해요.
다음 강의
문서를 읽고 남의 코드를 읽다 보면, 읽기 쉬운 코드와 어려운 코드가 확연히 보이기 시작해요. 다음 강의에서는 내가 쓰는 코드를 남이(그리고 석 달 뒤의 내가) 쉽게 읽을 수 있게 만드는 조건을 다뤄요.