[클린코드] 9일차/10일차 - 나쁜 주석이 될 수 밖에 없는 주석 조건

[클린코드] 9일차/10일차 - 나쁜 주석이 될 수 밖에 없는 주석 조건

클린코드 9일차 (p. 74~83(4장) )

클린코드 10일차 (p. 84~94(4장) )

4 주석

4. 나쁜 주석

1) 주절거리는 주석

- 특별한 이유 없이 의무감으로 한다면 시간 낭비이다.
- 주석을 달기로 결정했다면 충분한 시간을 들여 최고의 주석으로 달도록 노력하라.

 

2) 같은 이야기를 중복하는 주석

- 같은 코드 내용을 그대로 중복하는 주석은 피하라.

- 자칫 코드보다 주석 읽는 시간이 길어진다.

 

3) 오해할 여지가 있는 주석 ..Nope!

4) 의무적으로 다는 주석 ..Nope!!

5) 이력을 기록하는 주석 .. Nope!!

 

6) 있으나 마나 한 주석

- 너무 당연한 사실을 언급하는 주석으로 새로운 정보를 제공하지 못하는 주석

- 이렇게 지나친 참견을 주석을 달아놓으면 개발자는 주석을 무시하는 습관에 빠진다.

- 그렇게 자동으로 주석을 건너뛰고,,, 코드가 바뀌면서,,, 주석은 거짓말이 되고,,, 

- 당연한 사실을 주석으로 언급하지 말자.

---

 

나쁜 주석이 너무 많아 갑자기 좋은 주석은 뭐였는지 까먹었다... 좋은 주석은 .. 

1) 법적인 주석

2) 정보를 제공하는 주석

3) 의도를 설명하는 주석

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

5) 결과를 경고하는 주석

6) TODO 주석

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

---

 

7) 무서운 잡음

- 때로는 Javadocs도 잡음이다.

 

8) 함수나 변수로 표현할 수 있다면 주석...Nope!

- 아래의 예시처럼 주석 없이 코드로 표현할 수 있다면 주석이 필요 X

// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem - subsysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))

 

9) 위치를 표시하는 주석...Nope!

 

10) 닫는 괄호에 다는 주석

이와 같은 경우를 말하는 것 같다. 가독성이 1도 없군..

 

11) 공로를 돌리거나 저자를 표시하는 주석

- 위와 같은 정보는 소스 코드 관리 시스템에 저장하는 편이 좋다.

 

12) 주석으로 처리한 코드

- 주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 이유가 있을까봐

- 책에서 말했듯이 요즘 커밋 시 주석처리 된 코드가 있는지 한 번 확인하고 주석은 커밋하지 않는 습관을 들이는 중 ..!

- 주석 처리할 필요가 없다. 코드를 삭제하라 !! 잃어버릴 염려가 없다..

 

13) HTML 주석

- HTML 주석은 혐오 그 자체이다.

 

14) 전역 정보

- 주석을 달면 근처 코드만 기술하고, 시스템의 전반적인 정보를 기술하지 마라.

 

15) 너무 많은 정보

16) 모호한 관계

17) 함수 헤더