04. 주석

코드는 여기저기 움직이면서 변할 수 있으므로 주석이 미아가 되는 경우가 있음..

-> 따라서 부정확한 주석은 없는 것보다 훨씬 나쁘다!!

 

주석은 나쁜 코드를 보완하지 못한다

주석을 써서 수습하려 하지 말고 걍 코드를 다시 손보기

 

코드로 의도를 표현하라!

이름 잘 지으면 웬만하면 코드로 의도 다 표현할 수 있다. 

 

좋은 주석

제일 좋은 주석은 주석 안 다는 방법을 찾아낸 주석이다. 그래도 좀 필요한 주석들 몇가지

 

• 법적인 주석: 회사가 공통으로 지정한 주석
• 정보를 제공하는 주석: 반환값 설명 등
• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
• 결과를 경고하는 주석: 특정 테스트 케이스는 꺼야 할 때
• TODO 주석: 앞으로 해야할 일 정리
• 중요성을 강조하는 주석
• 공개 API에서 Javadocs

 

나쁜 주석

대다수 주석이 이 주석 유형이다. 최대한 없애기

 

• 주절거리는 주석: 애초에 적을 때부터 이해 잘 되게 적기, 필요없으면 삭제
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석: 살짝이라도 잘못된 정보가 있으면 틀어지기 쉬움
• 의무적으로 다는 주석
• 이력을 기록하는 주석: 이건 걍 아예 쓰지 말자
• 있으나 마나 한 주석
• 무서운 잡음: 복붙 실수..
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석: ///////// 식으로 배너 만들기는 가독성 낮춤
• 닫는 괄호에 다는 주석: 주석 대신 함수 줄이기 시도
• 공로를 돌리거나 저자를 표시하는 주석
• 주석으로 처리한 코드: 다른 사람들이 지워도 되나 망설이게 됨.. 싹 지우기
• HTML 주석: 알아보기도 힘든데 쓰지말자
• 전역 정보: 전반적인 정보 기술 시 알아보기 힘듬
• 너무 많은 정보
• 모호한 관계 
• 함수 헤더
• 비공개 코드에서 Javadocs

 

 

 

결론: 주석은 웬만하면 빼자.