[mjt] 잘 작성된 주석이란 무엇일까? 특징과 작성방법을 알아보자
[mjt] 잘 작성된 주석이란 무엇일까? 특징과 작성방법을 알아보자
주석은 어떻게 코드가 동작하는지, 왜 코드가 동작하는지를 설명하는데 사용된다. 주석은 정해진 방식이 없다보니 대부분 각자의 방식으로 작성하는데(사실 본인 ㅠㅠ) 잘 작성된 주석도 있으면 잘못된 방법의 주석도 있으며 어떤것들이 있는지 알아보자
좋은 주석이란 무엇인가?
주석에서 설명이 담긴 주석은 대개 좋지 않다고 한다. 그렇다면 좋은 주석이란 무엇인지 알아보자.
- 간결하면서도 명확한 정보를 제공하는 주석.
- 중복되거나 불필요하지 않은 주석.
- 현재 코드와 일치하는 최신 상태의 주석.
- 아키텍처를 설명하는 주석.
- 함수 용례와 매개변수 정보를 담고 있는 주석.
1-1) TODO, FIXME 태그 사용
개선해야 할 부분이나 버그를 명시적으로 기록한다.
// TODO: 향후 성능 최적화를 위해 debounce 함수 추가 필요
function handleInput(event) {
console.log(event.target.value);
}
1-2) 필요한 경우에만 작성
코드 자체로 의도가 명확한 경우 주석은 불필요함.
// Bad: 주석이 불필요한 경우
x = x + 1 # x 값을 1 증가시킴
// Good: 코드만으로도 충분히 이해 가능
x += 1
나쁜 주석이란 무엇일까?
위의 예시와 반대로 생각하면 될 것 같다. 내용은 아래와 같다.
-
중복된 주석: 코드와 동일한 내용을 설명하는 주석. -
오래된 주석: 코드가 변경되었지만, 주석이 업데이트되지 않은 경우. -
모호한 주석: 불분명하거나 오히려 혼란을 주는 주석.
주석 작성 요령
최대한 주석을 사용하지 않도록 변수와 함수 등을 통해 이해할 수 있게 작성하며, 팀 내에서 주석 작성 규칙을 합의하고 일관성을 유지하자. 만약, 주석이 너무 길어지거나 코드의 흐름을 방해하는 경우 별도의 문서로 정리하는 방법을 생각해보자.
3-1) 코드 리뷰에서 주석 검토
PR(풀 리퀘스트) 리뷰 시 주석도 코드처럼 검토.
3-2) 주석 스타일 가이드 사용
팀 내에서 주석 작성 규칙을 합의하고 일관성을 유지.
3-3) 주석 대신 의미 있는 이름 사용
주석 없이도 코드가 이해되도록 변수명, 함수명, 클래스명을 명확히 설정.
회고
이전에 함수를 만들 때 어떤 함수인지 어떻게 동작하는지 주석을 달았던 적이 있는데, 이번 공부를 통해 오히려 코드가 어떻게 동작하는지, 무엇을 하는지에 대한 주석은 좋지 않다라는 것을 새롭게 알게 되었다. 최대한 변수, 함수명에서 의도를 전달하도록 설명이 꼭 필요한 경우와 길 경우 다른 방법으로 팀원에게 공유하는 방식을 찾아보는것도 좋은 것 같다.