4장 주석

책의 내용 - 주석

💡 나쁜 코드에 주석을 달지 마라. 새로 짜라

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

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

제가 이렇듯 주석을 무시하는 이유가 무엇이냐고요? 거짓말을 하기 때문입니다.

항상도 아니고 고의도 아니지만 너무 자주 거짓말을 하기 때문입니다.

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

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

확실히 코드만으로 의도를 설명하기 어려운 경우가 존재합니다. 불행히도 많은 개발자가 이를 코드는 훌륭한 수단이 아니라는 의미로 해석합니다. 다음 예제를 살펴보겠습니다.
Java
```
//직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flage & HOURLY_FLAGE) && (employee.age > 65))
```
다음은 어떨까요?
Java
```
if (employee.isEligibleFourFullbenefits())
```
몇 초만 더 생각하면 코드로 대다수 의도를 표현할 수 있습니다.

좋은 주석

지금부터 밥값을 한다고 생각되는 주석을 몇 가지 소개합니다.

하지만 명심하길 바랍니다!

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

법적인 주석

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

결과를 경고하는 주석

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

Java

// 여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile()
{
    writeLinesToFile(1000000);

    reponse.setBody(testFile);
    reponse.readyToSend(testFile);
    String responseString = output.toString();
    assertSubString("Content-Length: 1000000", responseString);
    assertTure(bytesSent > 1000000);

}

TODO 주석

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

Java

// TODO-MdM 현재 필요하지 않다.// 체크아웃 모델을 도입하면 함수가 필요 없다.
protected VersionInfo makeVersion() throws Exception
{
    return null;
}

중요성을 강조하는 주석

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

Java

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

결론

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

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

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

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

책의 내용 - 주석

결론

댓글