4장 주석 - 좋은 주석

주석은 순수하게 선하지 못하다. 주석은 필요악이다.

프로그래밍 언어 자체가 표현력이 풍부하다면, 우리가 치밀하게 프로그래밍하면 안 쓸 수도 있기 때문이다.

주석은 우리가 코드로 의도를 표현하지 못해서 사용하는 것이다.

따라서 주석을 쓰기 전에 코드로 표현할 수 없을 지를 고민하자

 

주석은 거짓말을 한다. 현실적으로 프로그래머가 주석은 관리하고 최신화하지 않기 때문이다.

따라서 코드가 시간이 지남에 따라 거듭 변경되면 될 수록 코드와 주석은 점점 멀어진다.

아니, 분리된다.

 

거짓말하는 주석은 없는 주석보다 더 나쁘다.

 

반면에 코드를 보자, 코드는 항상 진실된 정보만 제공한다.

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

코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

표현력이 뛰어나며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 좋다.

 

코드로 의도를 표현하라

// 보너스 받을 자격을 검사한다.
if(employee.performance == "우수" && employee.age <=30)  //이런 것보다.
if(employee.isBenefit())  // 이게 가시성이 우수하다.

좋은 주석

좋은 주석은 글자 값을 한다.

하지만 명심하라! 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!

 

법적인 주석

저작권 정보, 소유권 정보 등은 필요하고 타당한 주석이다.

 

정보를 제공하는 주석

abstract 메서드의 경우 나중에 구현부가 될 정보를 알려준다.

의도를 설명하는 주석

구현이 조금 복잡하다면 이해를 도와주는 선을 넘어 의도를 설명하는 것도 나쁘지 않다

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

때때로 모호한 인수나 반환값은 그 의미를 읽기 좋게 포현하면 이해하기 쉬워진다.

인수나 반환값 자체를 명확히 하면 좋겠지만,

인수나 반환값이 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다

결과를 경고하는 주석(특히 테스트 케이스에서)

// 테스트 시간이 오래 걸립니다. 주의하세요!
public void _somethingTest(){
....

물론 요즘에는 @Ignore 속성을 이용해 테스트 케이스를 꺼버린다.

구체적인 설명은 @Ignore속성에 문자열로 넣어준다.

@Ignore("실행이 너무 오래 걸린다.")

JUnit4 가 나오기 이전에는 메서드 이름 앞에 _ 기호를 붙이는 관례가 있었다.

 

TODO 주석

TODO주석은 당장 구현하기 어려운 업무를 기술한다.

예를 들어 누군가에게 문제를 봐달라는 요청, 앞으로 발생할 이벤트에 맞게 고치라는 등등…

TODO주석은 IDE기능을 사용해 주기적으로 검사해서 제거해 나가야 한다.

 

중요성을 강조하는 주석

정말 중요한 정보를 강조하기 위함

공개 API에서 Javadocs

설명이 잘 된 공개 API는 참 유용하고 만족스럽다.

표준 자바 라이브러리에서 사용한 Javadocs가 좋은 예다.

자바 독이없다면 개발이 어려울 것

이처럼 공개 API를 구현한다면 반드시 훌륭한 Javadocs를 작성한다.