코드는 여기저기 움직이면서 변할 수 있으므로 주석이 미아가 되는 경우가 있음..
-> 따라서 부정확한 주석은 없는 것보다 훨씬 나쁘다!!
주석은 나쁜 코드를 보완하지 못한다
주석을 써서 수습하려 하지 말고 걍 코드를 다시 손보기
코드로 의도를 표현하라!
이름 잘 지으면 웬만하면 코드로 의도 다 표현할 수 있다.
좋은 주석
제일 좋은 주석은 주석 안 다는 방법을 찾아낸 주석이다. 그래도 좀 필요한 주석들 몇가지
- 법적인 주석: 회사가 공통으로 지정한 주석
- 정보를 제공하는 주석: 반환값 설명 등
- 의도를 설명하는 주석
- 의미를 명료하게 밝히는 주석
- 결과를 경고하는 주석: 특정 테스트 케이스는 꺼야 할 때
- TODO 주석: 앞으로 해야할 일 정리
- 중요성을 강조하는 주석
- 공개 API에서 Javadocs
나쁜 주석
대다수 주석이 이 주석 유형이다. 최대한 없애기
- 주절거리는 주석: 애초에 적을 때부터 이해 잘 되게 적기, 필요없으면 삭제
- 같은 이야기를 중복하는 주석
- 오해할 여지가 있는 주석: 살짝이라도 잘못된 정보가 있으면 틀어지기 쉬움
- 의무적으로 다는 주석
- 이력을 기록하는 주석: 이건 걍 아예 쓰지 말자
- 있으나 마나 한 주석
- 무서운 잡음: 복붙 실수..
- 함수나 변수로 표현할 수 있다면 주석을 달지 마라
- 위치를 표시하는 주석: ///////// 식으로 배너 만들기는 가독성 낮춤
- 닫는 괄호에 다는 주석: 주석 대신 함수 줄이기 시도
- 공로를 돌리거나 저자를 표시하는 주석
- 주석으로 처리한 코드: 다른 사람들이 지워도 되나 망설이게 됨.. 싹 지우기
- HTML 주석: 알아보기도 힘든데 쓰지말자
- 전역 정보: 전반적인 정보 기술 시 알아보기 힘듬
- 너무 많은 정보
- 모호한 관계
- 함수 헤더
- 비공개 코드에서 Javadocs
결론: 주석은 웬만하면 빼자.
'클린코드' 카테고리의 다른 글
03. 함수 (0) | 2022.01.30 |
---|---|
02. 의미 있는 이름 (0) | 2022.01.23 |
01. 깨끗한 코드 (0) | 2022.01.23 |