기타
코드 품질 개선 기법 26편: 설명의 핵심은 첫 문장에 있다
두줄요약
주석은 첫 문장에 가장 중요한 내용을 담아 개요를 먼저 전달해야 한다고 설명했습니다. 문서화 주석, 임시방편 코드, TODO 주석 모두 같은 원칙을 적용할 수 있다고 정리했습니다.
핵심 내용
- 문서화 주석과 인라인 주석에서 첫 문장에 핵심 개요를 담는 원칙
- 세부 구현보다 상위 추상화 수준의 설명 우선
- 임시방편 코드와 TODO 주석에서도 목적이나 이상 상태를 먼저 서술하는 방식
적용해볼 점
- 첫 문장만 읽어도 의도를 파악할 수 있는 주석 작성
- 예외 조건, 경계 조건, 세부 규칙은 뒤에 추가
- 주석의 시작점을 무엇으로 둘지 코드 성격에 맞게 조정