Clean code | 4장 주석

 

@Clean code | 4장 주석

 

 

 

-"나쁜 코드에 주석을 달지 마라. 새로 짜라."

• 잘 달린 주석은 그 어떤 정보보다 유용하고, 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만듬
• 오래되고 조잡한 주석은 잘못된 정보 퍼뜨림 -> 개발자들이 주석을 계속적으로 유지보수하기엔 현실적으로 불가능
• 코드 자체가 표현력이 풍부하다면, 개발자가 코드의 의도를 표현할 능력이 있다면, 주석은 거의 필요치 않음
• 애초에 주석이 필요없게끔 개발하기
• 코드만이 자신이 하는 일을 진실되게 말함(정확한 정보 제공하는 유일한 출처)

 

 

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

• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋음
• 코드 품질이 나쁘면 주석을 쓰기 보다는 그 시간에 코드를 다시 정리하기

 

 

-코드로 의도를 표현하라

• 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분함

 

 

-좋은 주석

• 법적인 주석(회사 등)
• 정보를 제공하는 주석 but 함수 이름에 정보를 담는 게 더 좋긴 함
• 개발자의 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석 but 더 나은 방법이 없는지 고민 후 정확히 달기
• 결과를 경고하는 주석 ex) Don't run if you don't have much time
• TODO 주석(앞으로 할 일) but TODO로 떡칠한 코드는 바람직하지 않음. 주기적으로 점검하기
• 중요성을 강조하는 주석(자칫 대수롭지 않다고 여겨질 뭔가의 중요성)
• 공개 API에서 Javadocs

 

 

-나쁜 주석

• 주절거리는 주석 -> 특별한 이유없이 주석 달지 않기
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석(모든 변수에 주석 달거나 하는)
• 이력을 기록하는 주석 -> 소스 코드 관리 프로그램 사용하면 됨
• 있으나 마나 한 주석(코드만 봐도 알 것 같은데 굳이 써 놓은..?)
• 무서운 잡음(복붙 잘못하거나 하는)
• 함수나 변수로 표현할 수 있다면 주석 달지 않기
• 위치 표시하는 주석(/////////등의 배너)
• 닫는 괄호에 다는 주석 -> 중첩 심하고 장황한 함수면 의미 있을지도 모르지만 작은 함수에는 잡음일 뿐
• 공로나 저자 표시하는 주석 -> 소스 코드 관리 프로그램 사용하면 됨
• 주석으로 처리한 코드 -> 사람들이 지우기 주저해 쓸모없는 코드가 점차 쌓여갈 수 있음
• HTML 주석 -> 편집기/ IDE에서조차 읽기 어려움
• 전역 정보 -> 주석을 달아야 한다면 근처에 있는 코드만 기술하기
• 너무 많은 정보(TMI 주의)
• 모호한 관계 -> 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 함
• 함수 헤더 -> 짧은 함수는 긴 설명이 필요 없음
• 비공개 코드에서 Javadocs