[노개북 1기] TIL (2022.01.28)

yourjin·2022년 2월 26일

클린코드

read.log

목록 보기

9/37

TIL (2022.01.28)

DAY 8

🔖 오늘 읽은 범위 : 4장, 주석( ~ p.75 좋은 주석)

😃 책에서 기억하고 싶은 내용을 써보세요.

Intro
- “나쁜코드에 주석을 달지 마라. 새로짜라.” - 브라이언 w. 커니핸, P.J. 플라우거
- 우리는 코드로 의도를 표현하지 못해 , 그러니까 실패를 만회하기 위해 주석을 사용한다.
- 그러므로 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다. 상황을 역 전해 코드로 의도를 표현할 방법은 없을까?
- 코드는 변화하고 진화한다.
- 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다.
주석은 나쁜 코드를 보완하지 못한다.
- 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
코드로 의도를 표현하라!
좋은 주석
- 하지만 명심하기 바란다. 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!
- 법적인 주석
  - 예를 들어, 각 소스 파일 첫머리에 주석으로 들어가는 저작권 정보와 소유권 정보는 필요하고도 타당하다.
- 정보를 제공하는 주석
```
/* Example 1 */
// 테스트 중인 Responder 인스턴스틀 반환한다. 
protected abstract Responder responderinstance( ) ;

/* Example 2 */
// kk: 11111: ss EEE, tff,1 dd, yyyy 형식이다. 
Pattern timeMatcher = Pattern. compile( "\\d*:\\d*:\\d* \\~, \\~ \\d*, \\d*'');
```
- 의도를 설명하는 주석
  - 때때로 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명 한다.
- 의미를 명료하게 밝히는 주석
  - 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
  - 물론 그릇된 주석을 달아놓을 위험은 상당히 높다.
- 결과를 경고하는 주석
  - // 여유 시간이 충분하지 않다면 실행하지 마십시오.
  - // SimpleDateFormat은 스레드에 안전하지 못하다. // 따라서 각 인스턴스를 독립적으로 생성해야 한다.
  - 프로그램 효율을 높이기 위해 정적 초기화 함수를 사용하려던 열성적인 프로그래머가 주석 때문에 실수를 면한다.
- TODO 주석
  - TODO 주석은 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다.
  - 하지만 어떤 용도로 사용하든 시스템에 나쁜 코드를 남겨 놓는 핑계가 되어서는 안 된다.
- 중요성을 강조하는 주석
- 공개 API에서 Javadocs
  - 여느 주석과 마찬가지로 Javadocs 역시 독자를 오도하거나, 잘못 위치하거나, 그릇된 정보를 전달할 가능성이 존 재한다.

🤔 오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

오늘은 일이 바빠 많은 부분을 읽지는 못했다. 하지만 적어도 “주석을 줄여!!!” 라는 메시지는 확실하게 받을 수 있었다. 대학교 시절에 나는 주석을 자세하게 남기는 것을 좋아했다. 이틀 뒤의 내가 오늘의 나의 생각을 100% 이해할 거라고 생각하지 않았기 때문이다. 팀플을 할 때도 마찬가지였다. 내가 주석을 남기면 다른 사람들이 내 코드를 더 쉽게 이해할 수 있을 것이라고 생각했다. 하지만 지금 생각해보니 나는 그들을 배려한 것이 아니라, 코드에 집중하기 어려운 나를 배려한 것이었다. 이 책에서 보여준 예시처럼 좋은 이름으로 모든 정보를 전달할 수 있다면, 주석은 불필요한 메모일 뿐이다.