클린코드 - 04. 주석

클린코드 - 04. 주석

주석은 양날의 검과 같습니다.
잘 달린 주석은 그 어떤 정보보다 유용할 수 있지만 반대라면?.. 오히려 코드를 이해하기 어렵게 만들 수도 있습니다.;;

그렇기 때문에 모든 개발자들이 의도에 맞게 코드를 정확히 작성한다면 (=표현) 주석은 필요하지 않을 수도 있습니다.
하지만 현실적으로 많은 어려움이 있기 때문에 코드의 의도를 보충하기 위해 주석을 사용하고는 합니다. 그리고 이에 따라 주석도 유지보수가 되어야하는 불편함이 생기기 때문에 필요할지라도 우리는 주석의 수를 줄이는데 노력해야합니다.

주석은 나쁜 코드를 보완하지 못하며 코드로 의도를 표현해야합니다.

좋은 주석이란? (최고의 주석은, 주석을 달지 않는 방법)

1. 법적인 주석
   1. 저작권 정보와 소유권 정보는 필요하고도 타당합니다.
2. 정보를 제공하는 주석
   1. 추상 메서드가 반환할 값을 설명합니다.
   2. 가능하다면 함수 이름에 정보를 담는 편이 더 좋습니다.
3. 의도를 설명하는 주석
4. 의미를 명료하게 밝히는 주석
5. 결과를 경고하는 주석
   1. 때로는 다른 프로그래머들에게 결과를 경고 할 목적으로 쓸 수 있습니다.
6. TODO 주석
   1. 앞으로 할일을 남기며 주기적으로 주석을 점검하여 없애도 괜찮은 주석을 삭제합니다.
7. 중요성을 강조하는 주석
8. 공개 API 에서 Javadocs
   1. 공개 API를 구현한다면 많은 이들에게 정보를 알리기 위해 사용할 수 있습니다.

 

나쁜 주석이란?

1. 주절거리는 주석
   1. 그저 중요한 정보 없이 의무감으로 작성하는 주석
2. 같은 이야기를 중복하는 주석
3. 오해할 여지가 있는 주석
4. 의무적으로 다는 주석
5. 이력을 기록하는 주석, 저자를 표시하는 주석
   1. 현재에는 소스 코드 관리 시스템이 존재하기에 혼란을 가중시킵니다.
6. 있으나 마나한 주석
7. 함수나 변수로 표현 할 수 있는 주석
8. 위치를 표시하는 주석
   1. handler나 function, actions등의 위치를 알리기 위한 주석
   2. // Actions ——————————-
9. 닫는 괄호를 표현하기위해 다는 주석
10. 주석으로 처리한 코드
    1. 이유가 있어서 주석처리를 했다고 생각하기 때문에 다른 사람들이 지우기를 주저할 수 있습니다.
11. HTML 주석
12. 전역 정보
    1. 주석을 달아야한다면 근처에 있는 코드만 기술하여야하며 전반적인 정보를 기술하는 것을 말합니다.
13. 너무 많은 정보
14. 모호한관계
15. 함수 헤더
16. 비 공개 코드에서의 사용