[클린 코드] 4장 주석

주석은 필요악

프로그래밍 언어로만 모든 의도를 표현하고 서로 이해할 수 있다면 주석은 필요하지 않음

우리는 프로그래밍 언어로만 의도를 전달하는 것을 실패하고 이를 만회하기 위해 주석을 사용한다.

즉 주석은 존재 자체가 표현을 제대로 하지 못한 실패의 산물이라는 것

 

주석이 악한 이유

주석은 거짓말을 한다.

오래될수록 코드와 멀어지고 그릇될 가능성이 커진다. 왜냐하면 코드를 유지보수하는 것도 어려운데 주석까지 유지 보수를 하는 것은 현실적으로 불가능하기 때문이다.

 

부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.

 

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

보통 주석을 추가하는 경우 코드 품질이 나쁘기 때문에 이를 보완하기에 작성한다.

하지만 주석을 다는 것보다 코드 품질을 올리는 것이 더 중요하다

 

// 직원이 복지 혜택을 받을 자격이 있는지 검사하는 코드

// 1
if((employee.flags & HOURLY_FLAG) && (employee.age > 65))

// 2
if(employee.isEligibleForFullBenefits())

코드만으로 의도를 표현하는 것은 어렵지만 좀 더 생각하면 방법을 찾을 수 있다. 

 

좋은 주석

법적인 주석

저작권 정보, 소유권 정보, 라이센스 등...

 

정보를 제공하는 주석

추상 메소드가 반환할 값을 설명하는 등의 기본적인 정보를 제공하는 주석

코드에서 사용한 정규표현식의 의미를 작성한 주석 등...

 

의도를 설명하는 주석

구현을 설명하는 것을 넘어 결정에 깔린 의도까지 설명하는 주석

 

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

모호한 인수나 반환값을 읽게 좋게 표현하면 이해하기 쉬워지지만, 인수나 반환값이 변경하지 못하는 코드에 속한다면 주석이 유용하다.

결과를 경고하는 주석

특정 테스트 케이스를 꺼야하는 이유를 설명하는 주석

 

TODO 주석

앞으로 할일을 남겨둔 주석

 

중요성을 강조하는 주석

대수롭지 않게 넘어갈 만한 것을 강조하는 주석

 

나쁜 주석

주절거리는 주석

특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하여 다는 주석

 

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

코드보다 더 많은 정보를 제공하지 못하는 주제에 비슷한 이야기를 반복하기에 코드에 덜 집중하게 만드는 나쁜 주석

 

오해의 여지가 있는 주석

 

의무적으로 다는 주석

 

이력을 기록하는 주석

 

있으나 마나 한 주석

너무나 당연한 사실을 언급하는 주석

 

위치를 표시하는 주석

 

닫는 괄호에 다는 주석

닫는 괄호에 주석을 달고 싶으면 함수를 줄이려 시도하자

 

주석으로 처리한 코드

주석으로 처리한 코드가 유용했을 때도 존재했지만 소스 코드 관리 시스템이 나온 이후부터는 그저 더미일 뿐이다.

 

HTML 주석

 

전역 정보

주석을 달아야 한다면 근처의 코드만 기술할 것

 

너무 많은 정보

 

함수 헤더