코드 주석, '왜' 뿐만 아니라 '무엇'을 설명해야 하는 이유
코드 주석은 '왜'를 설명해야 한다는 일반적인 통념과 달리, '무엇'을 설명하는 주석의 필요성을 제기하며, 코드의 가독성을 높이는 방법을 제시함.
Bob Martin의 'Extract Till You Drop' 예시를 통해, 과도한 함수 분할이 오히려 코드 이해를 어렵게 만들 수 있으며, 주석을 활용하여 가독성을 높이는 방안을 제시함.
커뮤니티에서는 의도를 설명하는 주석의 중요성을 강조하며, Rust 및 TypeScript의 주석 구분을 예시로 들어 주석의 다양한 활용 방안을 논의함.
주석의 역할: '무엇'과 '왜' 사이
일반적으로 주석은 코드의 '왜'를 설명해야 한다는 인식이 강하지만, 이 글에서는 코드의 '무엇'을 명확히 설명하는 주석의 중요성을 강조한다. 구체적으로, 코드의 의도를 주석으로 명시함으로써, 코드의 가독성을 높이고 유지보수를 용이하게 할 수 있다. 따라서, 함수 이름만으로는 부족한 부분을 주석으로 보완하는 것이 효과적이다.
코드 분할의 함정: 가독성 vs 복잡성
Bob Martin의 'Extract Till You Drop' 예시를 통해, 과도한 함수 분할이 오히려 코드 이해를 어렵게 만들 수 있음을 보여준다. 함수 분할은 코드의 재사용성을 높일 수 있지만, 코드의 흐름을 파악하기 어렵게 만들 수 있다. 반면, 주석을 활용하면 코드의 의도를 명확하게 전달하여 가독성을 높일 수 있으며, 유지보수에도 도움이 된다.
실전 적용 가이드: 주석 작성 전략
Rust와 TypeScript의 주석 구분을 참고하여, 주석을 문서화 주석과 개인적인 메모로 구분하여 활용할 수 있다. 문서화 주석은 코드의 '무엇'을 명확하게 설명하고, 개인적인 메모는 개발 과정에서의 생각을 기록하는 데 사용한다. 결과적으로, 코드의 가독성을 높이고, 협업 및 유지보수 효율성을 향상시킬 수 있다.
