아프니까 개발자다 아프니까 개발자다

"모든 함수에 설명서"는 왜 망하는가신규 프로젝트를 시작할 때 누군가 "모든 public 함수에 문서를 달자"고 하면 대부분 처음엔 진지하게 따른다. 3개월 뒤 현실은 둘 중 하나다. (1) 모든 함수에 "Does X."라는 의미 없는 한 줄이 붙어 있거나, (2) 시그니처는 바뀌었는데 docstring은 그대로 거짓말을 한다. 이게 "모든 함수 설명서" 규칙이 유지보수 불가능한 이유다.해법은 두 가지다. Type hints로 타입 계약을 선언하고, docstring으로 동작(behavior)만 서술한다. 타입은 자동 검증되고, docstring은 "왜 이렇게 동작하는지", "어떤 예외가 나는지"만 담는다. 2026년 Python 커뮤니티 best practice가 이 분리에 수렴했다.PEP 257 — ..