클린 코드 대신 읽어드립니다 _ 4. 주석 (정리, 요약, 후기)

 

1. 실패를 만회하기 위한 주석

우리는 코드로 의도를 표현하지 못해, 그러니까 실패를 만회하기 위해 주석을 사용한다. 여기서 내가 실패라는 단어를 썼다는 사실에 주목한다. 진심이다. 주석은 언제나 실패를 의미한다. 때때로 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다. 그래서 주석은 반겨 맞을 손님이 아니다.

그러므로 주석이 필요한 상황에 처하면 곰곰히 생각하기 바란다. 상황을 역전해 코드로 의도를 표현할 방법은 없을까? 코드로 의도를 표현할 때마다 스스로를 칭찬해준다. 주석을 달 때마다 자신에게 표현력이 없다는 사실을 푸념해야 마땅하다.

 

코드는 변화하고 진화한다. 일부가 여기서 저기로 옮겨지기도 한다. 조각이 나뉘고 갈라지고 합쳐지면서 괴물로 변한다. 불행하게도 주석이 언제나 코드를 따라가지는 않는다. 아니, 따라가지 못한다. 주석이 코드에서 분리되어 점점 더 부정확한 고아로 변하는 사례가 너무도 흔하다.

 

진실은 한곳에만 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 (간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

 

 

 

 

 

 

 

 

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다. 모듈을 짜고 보니 짜임새가 엉망이고 알아먹기 어렵다. 지저분한 모듈이라는 사실을 자가갛나다. 그래서 자신에게 이렇게 말한다. "이런! 주석을 달아야겠다!" 아니다! 코드를 정리해야 한다!

 

 

 

 

 

 

 

 

3. 코드로 의도를 표현하라!

 

 

 

 

 

 

 

 

 

4. 좋은 주석 / 나쁜 주석

좋은 주석 종류

- 법적인 주석 / 정보를 제공하는 주석 / 의도를 설명하는 주석 / 의미를 명료하게 밝히는 주석 / 결과를 경고하는 주석 / TODO 주석 / 중요성을 강조하는 주석 / 공개 API에서 Javadocs

 

나쁜 주석 종류

- 주절거리는 주석 / 같은 이야기를 중복하는 주석 / 오해할 여지가 있는 주석 / 의무를 다하는 주석 / 이력을 기록하느 주석 / 있으나마한 주석 / 위치를 표시하는 주석 / 닫는 괄호에 다는 주석 (닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 노력하자.) / 공로를 돌리거나 저자를 표시하는 주석 / 주석으로 처리한 주석 ( 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 이유가 있어 남겨놓았으리라고, 중요하니까 지우면 안 된다고 생각한다. 그래서 질 나쁜 와인병 바닥에 앙금이 쌓이듯 쓸모 없는 코드가 점차 쌓여간다. / 소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다. 이제는 주석으로 처리할 필요가 없다. 그냥 코드를 삭제하라. 잃어버릴 염려는 없다. 약속한다. ) / 너무 많은 정보 / 모호한 관계