읽기 좋은 코드가 좋은 코드다

5.주석에 담아야 하는 대상

 

- 주석의 목적은 코드를 읽는 사람이 코드를 작성한 사람만큼 코드를 잘 이해하게 돕는 데 있다.

 

📌 설명하지 말아야하는 것

- 코드에서 빠르게 유추할 수 있는 내용은 주석으로 달지 말라.

- 나쁜 이름에 주석을 달지 말고 이름을 고쳐라

- 나쁘게 작성된 코드를 보정하려고 애쓰는 주석을 달지 말고 코드를 수정해라

// 반환되는 항목의 수나 전체 바이트 수와 같이
// Request가 정하는 대로 Reply에 일정한 한계를 적용한다.
void ClieanReply(Request request, Reply reply);


== > 'clean'이 의미하는 바를 설명하지 말고 '한계를 적용한다'는 부분을 애초에 함수명에 포함하기
void EnforceLimitsFromRequest(...)

 

📌 무엇을 설명해야하는지?

- 중요한 통찰을 기록한 주석을 코드에 포함시키기

// 이 주먹구구식 논리는 몇 가지 단어를 생략할 수 있다. 100% 해결은 쉽지 않다

=> 이 주석이 없으면 코드를 읽는 사람은 뭔가 버그가 있다고 생각하고 버그 수정에 시간을 허비할 수 있다.

 

- 코드에 있는 결함을 설명하라

// TODO: 더 빠른 알고리즘을 사용하라.
// TODO(더스틴): JPEG말고 다른 이미지 포맷도 처리할 수 있어야한다.

=> 결함 설명하는 걸 부끄러워할 필요는 없다. 개선 아이디어 설명하는 게 좋음.

 

* 프로그래머 사이에서 널리 사용되는 표시

표시	보통의 의미
TODO	아직 하지 않은 일
FIXME	오동작을 일으킨다고 알려진 코드
HACK	아름답지 않은 해결책
XXX	위험! 여기 큰 문제가 있다.

 

 

📌 상수에 대한 설명

1. NUM_THREADS = 8 // 이 상수값이 2 * num_processors보다 크거나 같으면 된다.
=> 이 코드를 읽는 사람은 상수값을 어떻게 변경해야 하는지 알게 됨.

// 합리적인 한계를 설정하라 - 그렇게 많이 읽을 수 있는 사람은 어차피 없다.
2. const int MAX_RSS_SUBSCRIPTIONS = 1000;
=> 상수의 특정한 값이 아무런 의미를 갖지 않는 경우

3. image_quality = 0.72; // 사용자들은 0.72가 크기/해상도 대비 최선이라고 생각한다.
=> 상수 값이 신중하게 설정되었으므로 변경하지 않는게 더 좋은 경우

- 어떤 상수가 특정한 값을 갖게 된 '사연'

 

📌 글 쓰는 두려움을 떨쳐내라

1. 마음에 떠오르는 생각을 무조건 적어본다.

2. 주석을 읽고 무엇이 개선되어야 하는지 확인한다.

3. 개선한다.

 

 

 

📌 요약

- 코드를 읽는 사람이 자기가 작성한 코드의 어느 부분을 보고 '뭐라고?'라는 생각을 할지 예측해보고, 그 부분에 주석을 추가하라.

- 평범한 사람이 예상하지 못할 특이한 동작을 기록하라

- 파일이나 클래스 수준 주석에서 '큰 그림'을 설명하고 각 조각이 어떻게 맞춰지는지 설명하라

- 세부 코드를 읽다가 나무만 보고 숲은 못 보는 실수를 저지르지 마라.

 

 

 

 

https://www.yes24.com/Product/Goods/6692314

읽기 좋은 코드가 좋은 코드다 - 예스24