[클린코드] 4장- 주석

주석이 필요한 상황에 처하면 곰곰이 생각하기

상황을 코드로 전해 의도를 표현할 방법은 없는지?

주석은 오래 될수록 코드에서 멀어지고 완전하지 않을 가능성이 있음

프로그래머들이 주석을 유지하고 보수 하는건 현실적으로 불가능

코드는 진화하고 여기저기로 옮겨지지만 주석은 항상 따라가지 않으니까

→코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로 애초에 주석이 필요 없는 방향으로 에너지 쏟기

→코드만 진실 되게 말한다

 

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

코드에 주석을 추가하는 이유는 코드 품질이 나쁘기 때문임

자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신 난장판을 깨끗이 치우는데 시간을 보내라

 

코드로 의도를 표현하라

몇 초만 더 생각하면 코드로 대다수 의도를 표현할 수 있다

 

좋은 주석

-법적인 주석

 

-정보를 제공하는 주석

//테스트 중인 Responder 인스턴스를 반환한다
protected abstract Responder responderInstance();

//kk::mm::ss EEE, MMM dd , yyyy 형식이다
Pattern timeMatcher = Pattern.compile(
"\\\\d*:\\\\d*:\\\\d* \\\\w*, \\\\w* \\\\d*, \\\\d*");

-의도를 설명하는 주석

 

-의미를 명료하게 밝히는 주석

주석을 달 때는 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의 한다

 

결과를 경고하는 주석

 

TODO 주석

todo 주석은 프로그래머가 필요하다 여기지만 당장 구현이 어려운 업무를 기술한다

하지만 나쁜 코드를 남겨 놓는 핑계가 되어서는 안된다

todo로 떡칠한 코드는 x

주기적으로 투두 주석을 점검해 없애도 괜찮은 주석은 없애기

 

중요성을 강조한 주석

 

공개된 API에서 Javadocs

 

나쁜 주석

대다수의 주석이 이 범주임

허술한 코드를 지탱하거나 엉성한 코드를 변명하거나 미숙한 결정을 합리화하는 등

프로그래머가 주절거리는 독백에서 크게 벗어나지 못함

 

주절거리는 주석

의무감, 프로세스에서 하라고 하니까 마지 못해 주석을 달면 시간 낭비임

주석을 달기로 했다면 충분한 시간을 들여 최고의 주석을 달도록 하자

답을 알아내려면 다른 코드를 봐야하거나 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다 그런 주석은 바이트만 낭비할 뿐이다.

 

같은 이야기를 중복하는 주석

 

오해할 여지가 있는 주석

 

의무적으로 다는 주석

 

있으나 마나 한 주석

 

지나친 참견이 많은 주석은 개발자가 주석을 무시하는 습관에 빠지게 함

 

무서운 잡음

함수나 변수로 표현할 수 있다면 주석을 달지 마라

 

위치를 표시하는 주석

반드시 필요할 때만 아주 드물게 사용하는 편이 좋음 배너를 남용하면

독자가 흔한 잡음으로 여겨 무시한다

 

닫는 괄호에 다는 주석

중첩이 심하고 장황한 함수라면 의미가 있을 수도 있지만

우리가 선호하는 작고 캡슐화 된 함수에는 잡음일 뿐

닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자

 

공로를 돌리거나 저자를 표시하는 주석

 

주석으로 처리한 코드

그냥 코드를 삭제하라 소스코드 관리 시스템이 우리를 대신해 코드를 기억해준다

→ 나한테 제일 필요한 부분

 

HTML 주석

혐오 그 자체

 

전역 정보

주석을 달아야한다면 근처에 있는 코드에만 기술하라

코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라

 

너무 많은 정보

 

모호한 관계

 

함수 헤더

예제 부분이 최고임

-p 90참고