코드 품질 개선을 위한 주석 작성법

이 게시물은 코드 품질 개선과 개발 문화 향상을 위해 LY Corporation에서 실시하는 Review Committee 활동과 그 산출물인 Weekly Report 중 '설명의 핵심은 첫 문장에 있다' 주제를 다룹니다.

문서화 주석 작성의 중요성

• 첫 문장만 읽어도 함수의 개요를 이해할 수 있도록 작성해야 함
• 가장 중요한 설명 요소를 우선 선택하고, 코드보다 높은 추상화 수준으로 서술
• 예시로 영어 문자열을 문장과 단어 단위로 분할해 중첩 리스트를 반환하는 함수의 주석 개선 사례 제시

주석 작성 시 유의점

• 인라인 주석도 존재 이유를 먼저 설명하도록 개선
• TODO 주석은 이상적인 상태나 개선 방향을 먼저 기술하는 것이 효과적임