2. 주석 사용 지양해야하는 이유 - 클린 코드 4장

 

오늘은 객체지향적인 코드를 위해, 주석 사용을 하지 말아야하는 이유에 대해 말해보자

 

---

불분명한 주석, 오래된 주석, 불필요한 정보를 전달하는 주석은

코드 해석을 헷갈리게 만들 수 있다.

 

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


Brian Wilson Kernighan, Phillip James Plauger

 

주석 사용을 지양하라고 말하는 가장 큰 이유는

모든 주석을 계속 관리할 수 없기 때문

 

---

 

처음에 주석을 왜 사용하면 안되는지, 사수에게 물어봤을 때, 들은 답변이다.

 

지속적으로 관리되는 착한 주석은, 얼마든지 사용해도 좋다, 다만, 그건 너무 많은 불필요한 시관과 에너지 비용을 가져가는 일이다.

 

-> 또한, 내가 보는게 아닌 타인이 볼 때 잘못된 해석을 야기시킬수 있다.

 

그렇다면, 어떻게 코드에 대한 설명을 기록할 수 있을까..??

 

 

코드로 의도를 표현해라 

> 주석으로 의도를 표현

 

// 직원에게 복지 혜택을 받을 자격기 있는지 검사
if ((employee.flags & HOURLY_FLAG) && (Employee.age > 65))

> 코드로 의도를 표현

if (employee.isEligibleForFullBenefits())

 

출처: https://data-make.tistory.com/634 [Data Makes Our Future:티스토리]

 

 

➡️ 주석대신, 코드로 설명하자!

---

좋은 주석

 

주석이 꼭 나쁜다는게 아니다.

관리할 수 없는, 명확하지 않은 주석을 사용하지 말자는거지

 

1.  법적인 주석

•  저작권 정보와 소유권 정보를 담은 주석

2, 정보를 제공하는 주석

// kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Patter.compile(    "\\d*:\\d*:\\d* \\w*, \\w*, \\w*, \\d*");

// 테스트 중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();

 

3. 의도를 설명하는 주석

• 이게 조금 애매한것 같은데, 이 코드가 어떻게 돌아간다~~ 보다 / 이런 목적을 가졌다. 로 이해하면 좋을것 같다.

// 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도한다.
for (int i = 0; i < 25000; i++) {
  WidgetBuilderThread widgetBuilderThread =
    new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
  Thread thread = new Thread(widgetBuilderThread);
  thread.start();
}

 

4. 의미를 명확하게 밝히는 주석

• 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속할 경우

assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b

 

5. 경고하기 위한 주석

• 코드를 보는 다른 개발자에게 경고하기 위한 주석
• 하지만, 아래와 같은 경우는 @Ignore 어노테이션을 이용해서 메세지를 남기는 추세라고 한다.
• @Ignore("실행이 너무 오래 걸린다.")

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

 

6. TODO

• 앞으로 할일

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

TODO 주석은 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다.

• 더 이상 필요 없는 기능을 삭제하라는 알림
• 누군가에게 문제를 봐달라는 요청
• 더 좋은 이름을 떠올려달라는 부탁
• 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의

 

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

• 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해 주석을 사용

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

 

8. 공개 API

• 만약 공개 API를 만든다면, 자세하고 친절한 주석이 많은 이들에게 큰 도움이 될거라 생각한다.
• 하지만 이때도, 주석은 정말 신중하게 필요한 정보만 담겨야한다고 생각한다.

---

 

 

요약하자면, 주석은 꼭 필요할때에만 사용해야한다.

즉, 개발자가 주석을 무시하지 못하는 상황을 만들어야한다고 생각한다.

 

🚀 주석은 그정도로 중요한 부분에만 작성하도록 연습하자!!!

 

 

 

 

 

 

 

*참고

https://velog.io/@g0709-19/4%EC%9E%A5-%EC%A3%BC%EC%84%9D

https://hyesunzzang.tstory.com/141