[클린코드] 4장. 주석

 

 

---

결론

주석을 작성할 시간에 함수명, 변수명을 이해하기 쉽게 수정하거나 좀 더 간결하게 코드를 짜는 방법에 대해 고민하는 게 좋다👍

 

 

1. 주석을 최대한 쓰지 말자

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

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

② 이는 곧 작성자가 의도를 명확히 표현하지 못했다는 것을 뜻하기도 함

👉 난장판을 주석으로 설명하지 말고 개선하는데 시간을 보내자

 

✔ 주석은 방치된다.

① 코드의 변화에 따라가지 못하고, 주석은 방치된다.

② 방치된 주석은 뒤에 읽는 사람에게 혼용 야기 할 수 있다.

👉 관리 하지 못 할 거면 자제하는 것이 낫다.

 

2. 좋은 주석 👍

1) 법적인 이유로 다는 주석

//Copyright (C) 2003,2004,2005 by Object Mentor, Inc. All rights reserved 
//GNU General Public License 

 

2) 정보를 제공하는 주석

//휴대폰 000-000-0000 || 000-0000-0000
String PHONE_PATTERN = “^01(?:0|1|[6-9])-(?:\\d{3}|\\d{4})-\\d{4}$”;

//시분 HH24MI(0000~2359) 
String HH24MI_TIME_PATTERN = “^([01]\\d|2[0-3])([0-5])(\\d)$”;

//날짜 YYYY-MM-dd 
String DATE_PATTERN = “^([12]\\d{3}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01]))$”;

 

3) 의도를 설명하는 주석

아래 주석은 저자가 문제를 해결한 방식으로 저자의 의도가 분명하게 나타남

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

 

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

assertTrue(a.compareTo(a) == 0)  //a == a 
assertTrue(a.compareTo(b) != 0)  //a != b 
assertTrue(a.compareTo(ab) == 0) //ab == ab 
assertTrue(a.compareTo(b) != -1) //a < b 

👉 그러나 이러한 주석은 주석이 올바른지 검증하기 쉽지 않다는 문제가 있다. 따라서 위와 같은 주석을 달 때는 더 나은 방법이 없는지 먼저 꼭 고민해야 한다.

 

5) 결과를 경고하는 주석

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

 

6) TODO 주석

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

 

3. 주석보다 annotation

✔ annotation = 코드에 대한 메타 데이터

@Deprecated  //컴파일러가 warning을 발생시킴. IDE에서 사용시 표시됨 

@NotThreadSafe  //Thread Safe 하지 않음을 나타냄 (p74책에서는 주석으로 표현했지만, 어노테이션을 많이 사용)

@DisplayName //테스트 클래스 또는 테스트 메소드 의 사용자 정의 표시 이름을 선언 (이러한 주석은 상속 되지 않음)

👉 코드의 실행 흐름에 간섭을 주기도 하고, 주석처럼 코드에 대한 정보를 줄 수 있다.

 

4. 나쁜 주석💩

• 주절거리는 주석
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석 → 나쁜 습관🤦‍♂️
• 이력을 기록하는 주석 → 형상관리(git, svn)로 과거 이력 확인 가능하므로 필요없음
• 특정 위치를 표시하는 주석
• 닫는 괄호에 다는 주석
• 공로를 돌리거나 저자를 표시하는 주석
• HTML 주석
• 전역정보 (ex. Port 번호) → 정보 관리 못할 거면 안 다는게 나음
• 너무 많은 정보
• 모호한 관계 .. 등등

 

---

느낀점

- 책의 저자의 말을 읽을때마다 뼈를 때리는 듯한 충격을 받는듯했다. 😅
- 결국 나쁜 코드/주석 등을 만드는 건 작성자가 명확히 의도 표현하지 못했다는 뜻이고, 결국 주석 작성할 시간에 더 나은 코드로 가는 방향으로 가야 한다는데 깊이 공감을 했다.

- 이전 회사에서 작성한 코드를 봤을때 무분별한 주석이 남발되어 있는 것을 보고 '어떻게 이렇게 주석을 작성했었지?🤦‍♂️'라는 과거의 자신에게 반성을 하게 되는 챕터이기도 했다.

- 책을 읽으면서 깨달음을 얻는 것이 아주 흥미롭다.📚👨‍💻