주석과 이름

이름 하나가 주석 열 줄을 대체할 수 있어. 그리고 주석을 먼저 쓰면 설계가 따라와.

좋은 이름의 조건은 세 가지야. 첫째, 정확성. result, data, info 같은 이름은 아무것도 말해주지 않지. "이건 결과야"라고 하면 "뭐의 결과?"가 바로 따라오잖아. charCount, bytesSent, activeUsers 같이 이름만 봐도 뭘 담고 있는지 알 수 있어야 해. 둘째, 일관성. 같은 개념에는 같은 이름을, 다른 개념에는 다른 이름을 써야 해. 어떤 곳에서는 count를 쓰고 다른 곳에서는 num을 쓰면 혼란스럽지. 셋째, 적절한 길이. 좁은 범위에서는 i, j 같은 짧은 이름도 괜찮지만, 넓은 범위에서는 충분히 설명적인 이름이 필요해. 보통 2~3단어가 적절하고.

get, set, handle, process 같은 동사는 거의 모든 상황에 쓸 수 있어서 구체적인 정보를 전달하지 못해. getPage보다 fetchPageFromCache가 동작을 더 잘 설명하지. 오해의 소지가 있는 이름도 위험해. delete라고 해놓고 실제로는 비활성화만 하면, 사용자가 데이터가 진짜 삭제되었다고 착각할 수 있거든. 헝가리안 표기법(strName, intAge) 같은 건 현대 IDE에서는 불필요하고, 이름에는 의미론적 정보를 담아야지 문법적 정보를 담을 필요는 없어. 약어도 팀 내 합의된 것이면 괜찮지만, 임의로 줄이면 가독성이 떨어지지.

여기서 저자가 강조하는 관점이 있어 — 이름이 잘 안 지어지면 설계를 의심하라는 거야. 좋은 이름이 안 떠오르는 경우, 대부분은 대상의 역할이 불명확한 거거든. 클래스 이름을 뭘로 지을지 모르겠다면 그 클래스의 책임이 명확하지 않은 거고, 변수 이름이 안 떠오르면 그 변수가 담는 개념이 모호한 거야. 억지로 이름을 지으려 하지 말고, 설계를 다시 생각해보자. 클래스를 분리하거나, 메서드의 책임을 재정의하면 이름이 자연스럽게 따라와.

이름 이야기에서 자연스럽게 이어지는 게 주석을 먼저 쓰기야. 많은 개발자가 코드를 다 짠 후에 "이제 주석을 달아야지"라고 생각하는데, 이렇게 하면 주석은 거의 안 쓰게 돼. 코드가 이미 완성되었으니 급하지 않고, 다음 기능이 기다리고 있으니까. 저자는 이 순서를 뒤집으라고 해 — 코드 전에 주석을 먼저 써라. 새 클래스를 만들 때 코드 전에 인터페이스 주석을 먼저 쓰고, 새 메서드를 만들 때 구현 전에 메서드의 인터페이스 주석을 먼저 쓰고, 복잡한 로직 블록의 고수준 주석을 먼저 쓰는 거야.

이게 왜 좋냐면, 주석을 먼저 쓰면 설계를 먼저 생각하게 되거든. "이 메서드가 뭘 해야 하지?"를 주석으로 명확히 적어보면, 메서드의 역할과 인터페이스가 자연스럽게 정리돼. 반대로 코드를 먼저 짜면, 구현에 끌려다니면서 "이 매개변수도 필요하네", "이 예외도 던져야겠네" 하면서 인터페이스가 점점 복잡해지지.

진짜 위력은 설계 피드백 루프에 있어. 인터페이스 주석을 쓰다가 주석이 너무 길어지면 메서드가 너무 많은 일을 하고 있다는 신호고, 주석에 구현 세부사항이 들어가면 추상화가 부족하다는 신호야. 주석이 쓰기 어렵다면 메서드의 목적이 불명확한 거고, 다른 메서드와 겹치면 중복이 있는 거야. TDD에서 테스트를 먼저 쓰면 인터페이스가 정리되듯이, 주석을 먼저 쓰면 추상화가 정리되는 거지. 저자는 이걸 "Comment-Driven Design"이라고 부를 수 있다고 해.

실전에서는 새 파일을 만들 때 상단에 모듈의 전체 목적을 한두 줄로 쓰고, 새 클래스를 만들 때 클래스 수준 주석으로 책임과 사용 시나리오를 적고, 새 메서드를 만들 때 무엇을 하는지와 매개변수/반환값/예외 상황을 적어. 주석을 먼저 쓰면 코드가 주석을 따라가는 구조가 되고, 코드와 주석의 불일치도 줄어들어.

---

정리

5장 읽고 기억할 거 세 가지:

1. 좋은 이름의 조건은 정확성, 일관성, 적절한 길이야. 이름이 안 떠오르면 설계가 불명확하다는 신호니까, 억지로 짓지 말고 설계를 다시 생각해보자
2. 코드 전에 주석을 먼저 써라. 주석을 먼저 쓰면 설계를 먼저 생각하게 되고, 더 깔끔한 추상화가 나와
3. 주석이 길어지거나 쓰기 어려우면 설계가 잘못된 신호야. 주석은 설계를 검증하는 도구로 활용할 수 있어