좋은 주석을 적는 방법

주석[Tin]

 

1. 코드 내용을 그대로 반복하는, 즉 추가 정보가 없는 주석은 적지 말라.

2. 좋은 주석은 불명확한 코드를 변명하지 않는다. - 주석으로 코드를 설명하지 말고 코드를 다시 써라.

3. 명확한 주석을 적을 수 없다면 코드를 회고하자. - 코드가 어렵다고 주석으로 경고하지 말고 코드를 다시 써라.

4. 주석은 혼란을 야기하는 것이 아니라 해소해야 한다. - 주석을 보고 더 헷갈린다면 그 주석은 지우는 편이 맞다.

5. 관용적이지 않은 코드는 주석으로 설명하라. - 불필요하거나 중복된다고 생각할 수 있는 코드, 이로 인하여 다른 누군가가 "단순화" 할 수도 있다고 생각되는 코드라면 주석을 달아 설명해두는 것이 좋다.

6. 복사한 코드라면 원본 출처 링크를 주석에 포함하라.

- 향후 코드를 읽을 동료가 전체 컨텍스트(어떤 문제, 해당 솔루션이 권장되는 이유 등)을 파악하는 데 도움이 될 수 있다.

7. 도움이 될 만한 외부 참조 링크를 포함하라.

8. 코드를 수정할 때, 특히 버그를 수정할 때 주석을 추가하라.

9. 주석을 사용해 불완전한 구현을 표시하라. - 기술 부채를 측정하고 해결하는 데에 도움이 된다.

 

그리고 그에 대한 상세 설명.

https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/

Best practices for writing code comments