코드에 주석을 작성하는 것은 개발자로서 지켜야 할 중요한 원칙 중 하나로 주석은 코드의 해석을 돕고 팀원들과의 원활한 협업을 도와준다 그러나 부적절한 주석은 오히려 오해를 불러와 피해를 줄 수 있으므로 주석 작성법을 정확히 알고 있어야 한다
그렇기에 이번 글에선 올바르게 주석을 작성하는 법에 대해 소개하려고 한다
1. 의도를 명확히 해야 한다
코드가 어떻게 작동하는지보다는 왜 해당 코드가 필요한지 주석으로 설명해야 한다 예를 들어 특별한 알고리즘나 해결책의 사용 이유, 복잡한 비즈니스 로직 또는 특정한 결정의 배경에 대한 내용이 필요할 수 있다
이러한 내용은 코드만으로는 전달하기 어렵기 때문에 주석을 통해 명확하게 전달하는 것이 중요하다
2. 주석은 간결하게 해야 한다
불필요한 세부 정보는 주석에서 배제해야 한다 주석에선 꼭 필요한 내용만 간결히 작성하도록 한다
3. 주석을 최신 상태로 유지해야 한다
코드가 변경되면 주석도 함께 수정해야 한다 오랜된 주석은 오히려 코드 이해를 방해하기에 주석을 항상 최신으로 만들어 이러한 문제가 생기지 않도록 한다
4. 코드는 읽기 쉽게 작성해야 한다
코드가 스스로 설명될 수 있도록 의미 있는 변수명과 함수명을 사용해야 한다 일일히 주석을 달아서 코드를 작성하는 것 보단 코드 자체를 읽기 쉽게 만드는 것을 지향하여 불필요한 주석 사용을 줄인다
이렇게 코드의 자체 품질을 높이는 것은 주석의 필요성을 줄이는 가장 효과적인 방법으로 좋은 코드는 주석 없이도 자체적으로 설명서의 역할을 할 수 있어야 한다
5. 주석의 위치를 적절히 결정해야 한다
당연하다고 생각할 수도 있지만 주석은 해당 코드 바로 위나 옆에 위치시켜야 한다
추가로 주석이 코드의 흐름을 방해할 수 있으므로 복잡한 로직의 앞 부분에 요약 주석을 추가하는 것이 도움이 될 수 있다
6. 불필요한 정보는 주석에서 제외해야 한다
코드에 굳이 필요없는 저자의 이름이나 날짜 같은 정보는 주석에서 피해야 한다
현재는 버전 관리 시스템(VCS) 같은 도구를 사용하여 코드의 변경 히스토리와 저자 정보를 쉽게 파악할 수 있으므로 이러한 정보는 주석에서 생략하는 것이 좋다
7. TODO 주석을 적절히 활용해야 한다
앞으로의 작업이나 수정 사항을 표시하기 위해서는 일반 주석이 아닌 TODO 주석을 사용하여 명확히 표현하도록 한다
그러나 TODO를 남발하면 코드 내에서 해야 할 일이 무한정 쌓일 수 있으므로 주기적으로 확인하고 해결해야 한다
8. 문서화 주석을 사용해야 한다
함수나 클래스, 모듈에 대한 설명을 작성할 때는 문서화 주석을 활용해야 한다
9. 주의사항과 경고는 명확히 표시해야 한다
특별한 주의가 필요한 코드 부분은 주석으로 꼭 표시해야 한다 그래야 다른 사람이 코드를 사용하거나 시간이 지난 후에 사용하여도 문제를 방지할 수 있다
10. 전제조건과 후속조건을 명확히 해야 한다
함수나 알고리즘의 전제조건이나 후속조건은 주석으로 명확히 나타내야 한다 9번과 마찬가지로 전제조건과 후속조건을 명확히 하여 다른 사람이 코드를 사용하거나 시간이 지난 후에 사용하여도 문제를 방지할 수 있으며 테스트의 품질을 높이는데 도움이 된다
끝으로
코드 주석은 코드의 설명서로 주석의 품질과 연관성에 주의를 기울이며 주석을 관리해야 한다 또한 주석은 항상 반복적인 검토와 리팩토링을 필요로 하기에 이러한 작업은 주석만의 품질 향상이 아니라 코드 전체의 품질 향상에도 도움을 줄 수 있다
마치며 해당 글을 읽기 전이나 때론 읽고나서도 코드 주석 달기와 같은 노력은 굳이 쓸모없다고 느낄 수 있으나 해당 행동을 통해 우리의 코드는 더욱 더 명확하고 알기 쉬워지는 좋은 코드가 될 것이다