코드 품질 개선 기법 26편: 설명의 핵심은 첫 문장에 있다 (새 탭에서 열림)
코드의 가독성과 유지보수성을 높이기 위해서는 주석의 첫 번째 문장에 가장 핵심적인 정보를 담는 것이 중요합니다. 단순히 코드의 동작 과정을 나열하기보다 높은 추상화 수준에서 코드의 목적을 먼저 설명해야 하며, 이를 통해 읽는 사람이 전체 맥락을 빠르게 파악할 수 있도록 유도해야 합니다. 주석의 유형에 따라 가장 중요한 요소(반환값, 존재 이유, 이상적인 상태 등)를 선별하여 서두에 배치하는 것이 문서화의 핵심입니다. **효율적인 문서화 주석 작성법** - **첫 문장에서 개요 전달**: 문서화 주석은 전체를 다 읽지 않고 첫 번째 문장만 읽어도 해당 함수나 클래스의 역할을 이해할 수 있도록 작성해야 합니다. - **추상화 수준 높이기**: "마침표로 분할한다"와 같은 구현 디테일보다는 "문장 단위로 분할한다"처럼 코드보다 높은 수준의 용어를 사용하여 의도를 명확히 합니다. - **중요 정보 우선 배치**: 함수의 경우 '무엇을 반환하는지'가 가장 중요하므로, 반환값의 의미를 첫 문장에 기술하고 구체적인 구분자나 예외 처리 조건은 뒷부분에 보충합니다. - **구체적인 예시 활용**: 경계 조건이나 복잡한 입력값이 있을 때는 주석 하단에 `input -> output` 형태의 예시를 추가하여 이해를 돕습니다. **임시 방편 및 인라인 주석의 구성** - **존재 이유 명시**: 특정 버그를 회피하기 위한 코드나 임시 방편적인 코드에서는 '무엇을 하는지'보다 '왜 이 코드가 필요한지'를 먼저 설명해야 합니다. - **맥락 제공**: 예를 들어 "기기 X의 버그를 해결하기 위함"이라는 목적을 서두에 두면, 나중에 코드를 읽는 작업자가 해당 로직의 삭제 여부를 더 쉽게 판단할 수 있습니다. **효과적인 TODO 주석 작성** - **목표 상태 우선 기술**: TODO 주석에서는 앞으로 수행해야 할 리팩토링의 방향이나 '이상적인 상태'를 가장 먼저 작성합니다. - **제약 사항 후순위 배치**: 현재 상태의 문제점이나 즉시 수정하지 못하는 기술적 부채에 대한 설명은 목표를 명시한 뒤에 덧붙이는 것이 가독성에 유리합니다. 코드의 의미는 코드가 스스로 말해야 하지만, 그 너머의 의도와 비즈니스 로직의 맥락은 주석의 첫 문장이 결정합니다. 읽는 이의 시간을 아끼기 위해 가장 중요한 핵심부터 말하는 습관을 들이는 것이 좋습니다.