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

코드 품질 및 개발 문화 개선

• LY Corporation은 높은 개발 생산성을 위해 Review Committee 활동을 통해 코드 리뷰 피드백과 Weekly Report를 공유.
• 이 보고서 중 일반적인 주제를 코드 품질 개선 기법 시리즈로 연재. 문서화 주석 개선 방안
• 설명의 핵심은 첫 문장에 있어야 하며, 개요를 파악할 수 있도록 작성.
• 가장 중요한 요소를 선택하고, 코드보다 높은 추상화 수준으로 설명해야 함.
• 예시: 함수가 '영어 문자열을 문장 단위로, 다시 단어 단위로 분할하여 리스트의 리스트를 반환'한다고 첫 문장에 명시. 다른 주석에도 적용
• 인라인 주석이나 TODO 주석도 무엇을 먼저 설명할지 신중하게 선택.
• 임시방편 코드는 '존재 이유'를, TODO 주석은 '이상적인 상태'를 먼저 기술하는 것이 효과적.