주석, 첫 문장으로 모든 것을 말하라!
by DD
5개월 전
조회수 27
LY Corporation의 코드 품질 개선 노력의 일환으로, 주석 작성 가이드라인을 제시함
문서화 주석의 핵심은 첫 문장에 있으며, 가장 중요한 요소를 먼저 설명해야 함
TODO 주석과 인라인 주석 작성 시에도 '무엇을 먼저 설명할지'를 신중하게 선택하여 코드 가독성을 높여야 함
주석, 왜 첫 문장이 중요한가?
주석은 코드의 이해도를 높이는 중요한 수단이다. 문서화 주석의 경우, 첫 문장에서 함수의 핵심 기능을 명확히 설명해야 한다. 따라서, 코드의 추상화 수준을 높여 핵심 내용 전달에 집중해야 한다. 가독성을 높여 유지보수성을 향상시키는 것이 목표이다.
주석 작성, 무엇을 먼저 써야 할까?
주석 작성 시, '무엇을' 설명할지 신중하게 선택해야 한다. TODO 주석의 경우, '어떻게' 개선할지보다 '왜' 개선해야 하는지, 즉 문제 상황을 먼저 명시해야 한다. 인라인 주석 역시, 코드의 의도와 목적을 먼저 설명하여 코드의 이해도를 높여야 한다.
주석 개선, 실전 적용 가이드
주석 작성 시, 코드의 추상화 수준을 고려하여 핵심 내용을 먼저 설명한다. 예시 코드와 함께 주석을 작성하여 이해도를 높인다. 코드 리뷰를 통해 주석의 적절성을 검토하고, 지속적으로 개선해 나간다. 결과적으로 코드 품질과 개발 생산성을 향상시킬 수 있다.
