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

1. 문서화 주석 작성 원칙

• 목표: 복잡하거나 직관적이지 않은 코드의 이해를 돕기 위해 문서화 주석 활용
• 핵심 원칙: 첫 문장만 읽어도 개요를 파악할 수 있도록 작성
  • 가장 중요한 요소 선택: 함수의 핵심 목적이나 반환값 등을 먼저 명시
  • 높은 추상화 수준: 코드 자체보다 상위 레벨에서 설명
• 예시: '문자열의 중첩 리스트를 반환한다'는 것을 첫 문장으로 제시하고, 분할 기준 등 세부 사항은 뒤에 추가
• 추가: 코너 케이스나 경계 조건이 많을 경우 인수 및 반환값 예시 제공

2. 문서화 주석 외 주석 작성 시 고려사항

• 인라인 주석: 임시방편 코드의 경우, '무엇을 하는지'보다 **'존재 이유'**를 먼저 설명하는 것이 효과적
• TODO 주석: '앞으로 어떻게 하고 싶은지' 또는 '이상적인 상태'를 먼저 기술하고, 현재 상태가 좋지 않은 이유나 즉시 개선하기 어려운 이유 등을 부연 설명

결론

• 주석 작성 시 무엇을 먼저 설명할지 신중하게 선택하는 것이 중요합니다.
• 명확하고 간결한 첫 문장은 코드의 가독성과 유지보수성을 크게 향상시킵니다.