[리뷰] 클린코드 Clean Code 4장 - 주석

책의 내용 - 주석

나쁜 코드에 주석을 달지 마라. 새로 짜라
- 브라이언 w. 커니핸, P.J 플라우거

잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 

사실상 주석은 기껏해야 필요악이다. 

내가 이렇듯 주석을 무시하는 이유가 무엇이냐고? 거짓말을 하니까.

항상도 아니고 고의도 아니지만 너무 자주 거짓 말을 하니까.

 

 

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

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

 

*코드로 의도를 표현하라!

확실히 코드만으로 의도를 설명하기 어려운 경우가 존재한다. 불행히도 많은 개발자가 이를 코드는 훌륭한 수단이 아니라는 의미로 해석한다. 다음 예제를 살펴보자.

//직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flage & HOURLY_FLAGE) && (employee.age > 65))

다음은 어떠한가?

if (employee.isEligibleFourFullbenefits())

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

 

*좋은 주석

지금부터 글자 값을 한다고 생각하는 주석을 몇 가지를 소개한다.

하지만 명심하길 바란다!

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

 

1. 법적인 주석

회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시한다. 예를 들어, 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보 소유권 정보 정도

 

2. 결과를 경고하는 주석

때로 다른 프로그래머에게 결과를 경고할 목적으로 주석을 사용한다.

// 여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile()
{
	writeLinesToFile(1000000);
    
    reponse.setBody(testFile);
    reponse.readyToSend(testFile);
    String responseString = output.toString();
    assertSubString("Content-Length: 1000000", responseString);
    assertTure(bytesSent > 1000000);
   
}

 

3. TODO 주석

때로는 '앞으로 할 일'을 //TODO 주석으로 남겨두면 편한다.

// TODO-MdM 현재 필요하지 않다.
// 체크아웃 모델을 도입하면 함수가 필요 없다.

protected VersionInfo makeVersion() throws Exception
{
	return null;
}

 

4. 중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해서도 주석을 사용한다.

String listItemContent = match.group(3).trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
new ListItemWidget(this, listItemContent, this.level + 1)
return buildList(text.substring(match.end()));

 

결론

오늘은 4장 주석에 대해 읽었다.

어제 함수의 내용보다는 읽히는데 쉬웠고, 특히 내가 주의 깊게 본 부분은

'주석은 거짓말을 많이 하고, 또한 주석을 최대한 달지 않고 코드로 의도를 표현한다'는 대목이었다. 

항상 코드를 변경할 때 주석이 달려 있으면, 같이 수정하도록 하고, 의도를 분명하게 표현하도록 하자!