좋은 주석을 적는 방법
1. 주석은 코드를 복제하면 안된다.
처음 프로그래밍을 할 때, 모든 코드 줄에 주석을 달도록 요구하지만 이 훈련은 처음에만 유효할 뿐이지 성장을 했다면 제거해야합니다.
정보를 추가하지 않는 주석은 다음과 같은 이유로 제거해야합니다.
- 시각적으로 혼란을 줄 수 있다.
- 쓰고 읽는 시간이 오래걸린다.
예시를 들어보겠습니다.
i = i + 1; // Add one to i위의 주석은 어떠한 정보도 추가하지 않으며, 유지 관리 비용이 발생됩니다.
2. 좋은 주석은 불명확한 코드를 변명하지 않는다.
주석의 또 다른 오용은 코드에 있어야할 정보를 제공하는 것입니다.
예시를 들어보겠습니다.
# n은 입력받은 매개변수 2개를 더하는 함수입니다.
def n(x, y) :
return x + y위의 주석처럼 함수명으로 함수의 역할을 전달할 수 있음에도 주석을 사용하는 경우는 잘못된 경우입니다.
def add_num(x, y) :
return x + y3. 명확한 주석을 작성할 수 없는 경우, 코드에 문제가 있을 가능성이 있다.
작성한 코드가 어렵다고, 주석으로 그 코드를 대변하면 안됩니다.
이러한 경우, 주석으로 대변하는 것보다 코드를 다시 쓰는 것이 좋습니다.
4. 주석은 혼란을 야기하는 것이 아니라 해소해야 합니다.
코드를 설명하는 주석을 보고 코드에 대해 혼란성을 줄 수 있는 주석이라면 지워야합니다.
5. 관용적이지 않은(unidiomatic) 코드는 주석으로 설명하라.
다른 사람이 불필요하거나 중복된다고 생각할 수 있는 코드에 주석을 추가하는 것이 좋습니다.
코드를 작성하다보면 각자의 개발 환경이나 개발해야할 기능에 따라 필요성이 있는 코드가 나눠지거나 중복되기 마련입니다.
그럴 경우, 주석으로 그 코드의 부분을 설명하는 것을 추천합니다.
6. 복사한 코드의 원본 코드에 대한 링크를 제공한다.
코드를 작성하다보면, 인터넷에서 코드를 가져와 자신의 코드에 적용하는 경우가 많습니다.
그 후, 코드를 완성하고, 다른 사람들에게 자신의 코드를 설명할 기회가 주어졌을 때 인터넷에서 가져온 코드에 대해 질문을 할 수 있습니다.
- 어떤 문제때문에 코드를 적용하였는지?
- 코드를 제공한 사람은 누구인지?
- 작동 원리
...
이러한 경우, 대부분 정확한 답변을 하지 못하며, 답변을 하더라도 원본코드 작성자의 의도와 일치하는지 의문이 있을 수 있습니다.
이때 원본 코드의 URL을 주석으로 처리하여 가져온 코드 근처에 두면, 질문자들이 주석을 참조하여 가진 궁금증을 풀 수 있습니다.
7. 도움이 될 외부 참조 링크를 포함하라
표준 및 기타 설명서에 대한 링크는 독자가 코드로 해결하는 문제를 이해하는데 도움이 될 수 있다.
잘 배치된 주석은 독자에게 가장 필요한 시기와 위치에 포인터를 제공한다.
8. 버그를 수정할 때, 주석 추가
코드를 처음 작성할 때뿐만 아니라 수정할 때, 버그를 수정할 경우 주석을 추가해야합니다.
버그를 수정할 경우 추가한 주석은 독자가 현재 및 참조된 메서드의 코드를 이해하는데 도움이 될 뿐만 아니라 코드가 여전히 필요한지 여부와 테스트 방법을 결정하는데 도움이 됩니다.
또, 이슈 트래커를 참조하는 것도 도움이 될 수 있습니다.
9. 주석을 사용하여 불완전한 코드 구역 표시
불완전한 코드가 있더라도 체크해야 하는 경우가 있습니다.
코드에서 알려진 결함을 공유하지 않으려는 경우도 있지만, TODO 주석으로 이를 명시적으로 지정하는 것이 좋습니다.
// TODO : We...
// regardless of the locale of the phone. We need to think about
// how to allow comma as decimal separator, which will require
// updating number parsing and other places that transform numbers 위처럼 주석에 사용하면 기술 부채를 측정하고 해결하는데 도움이 됩니다.
더 나아가 트래커에 문제를 추가하고 의견으로 문제를 참조하는 방법입니다.
결론
모든 부분에 예시가 있는 것은 아니지만, 참조하여 잘못된 코드를 변명하거나 수정하지 않는 주석으로 사용하지 않는 목적을 가지고 작성하였습니다.
참조 레퍼런스
https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/
