코드 품질 개선 기법 26편: 설명의 핵심은 첫 문장에 있다

Context

클래스나 함수가 복잡하거나 직관적이지 않을 때 작성하는 문서화 주석이 세부 구현 방식부터 설명하면 전체 문맥을 파악하기 어렵다.

Technical Solution

• 첫 문장에 가장 중요한 요소를 배치: 함수의 목적이나 반환값의 의미를 추상화 수준 높게 설명
• 세부 사항은 그 뒤에 기술: "어떤 문자로 분할할지"나 "어떤 것을 제외할지" 같은 구현 세부사항을 별도 문장으로 분리
• 예시 코드 포함: 코너 조건이나 경계 조건이 많을 때 입출력 예시(" a bc. .d,,."→[["a", "bc"], ["d"]])를 제시
• 인라인 주석의 우선순위 조정: 임시방편 코드에서는 "무엇을 하는지"보다 "왜 이 코드가 필요한지" 존재 이유를 먼저 기술
• TODO 주석 구조 재정의: "앞으로 어떻게 할지"라는 이상 상태를 먼저 작성한 후 "현재 상태가 좋지 않은 이유"를 기술

Key Takeaway

주석 작성 시 가장 중요한 정보를 먼저 배치하고 추상화 수준을 높일수록 첫 문장만으로도 코드의 목적을 신속하게 파악할 수 있다.