[읽코좋코] 주석

주석의 목적은?

- 코드를 읽는 사람이 코드를 작성한 사람만큼 이해를 돕기 위함이다.

 

// 클래스 Account를 위한 정의
class Account{
	pubilc:
    //생성자
    Account();
    
    //profit에 새로운 값을 설정
    void SetProfit(double profit);
    
    //이 어카운트의 profit을 반환
    double GetProfit();
}

- 위 코드의 주석은 모두 가치가 없는 주석이다 

- 새로운 정보가 전혀 없고 아무런 도움을 주지 못하기 때문이다.

 

// 주어진 이름과 깊이를 이용해서 서브트리[h1]에 있는 노드를 찾는다.
Node* FindNodeInSubtree(Node* subtree, string name, int depth);

- 이 주석 또한 '무가치한 주석'에 속하며, 함수의 선언과 주석 내용이 실질적으로 일치하기 때문에 굳이 필요없으며, 지우거나 개선해야한다.

 

//주어진 'name'으로 노드를 찾거나 아니면 NULL을 반환한다.
//만약 depth <= 0 이면 'subtree'만 검색된다.
//만약 depth == N이면 N레벨과 그 아래만 검색된다.
Node* FindNodeInSubtree(Node* subtree, string name, int depth);

- 차라리 이렇게 중요 세부 사항을 적는것이 낫다고 한다.

 

---

 

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

- 위 코드의 주석은 코드에 대한 설명이 아닌 'clean'이 의미하는 바를 설명하려 한다. 

 

//'reply'가 count/byte/등과 같이 'request'가 정하는 한계조건을 만족시키도록 한다.
void EnforceLimitsFromRequest(Request request, Reply reply);

- 이 함수명은 전보다 더 '스스로 설명하는' 느낌이 강하며, 좋은 이름은 함수가 사용되는 모든 곳에서 드러나므로 좋은 주석보다 낫다고 한다.

- 즉 나쁜 이름에 주석을 달지말고 그 대신 이름을 고치라는 의미다

 

---

 

//놀랍게도, 이 데이터에서 이진트리는 해시테이블보다 40%정도 빠르다.
//해시를 계산하는 비용이 좌/우 비교를 능가한다.

 

- 이러한 주석은 읽는 사람이 코드를 최적화 하느라 시간을 허비하지 않게 도와주는 주석이다.

 

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

- 이 주석이 없으면 코드를 읽는 사람이 버그가 있다고 생각하고 실패를 찾기 위한 테스트 케이스, 버그를 수정하는 시간을 허비할지 모른다.

- 즉, 주석으로 인해 문제가 있다는 것을 빠르게 판단한다는 의미다

 

//이 클래스는 점점 엉망이 되어가고 있다. 어쩌면 'ResourceNode'하위 클래스를
//만들어서 정리해야 할지도 모른다.

- 이 주석은 현재 코드가 엉망이라는 것을 밝히고 다음 사람이 어떻게 수정할지 알려줄 수 있는 이정표가 된다.

- 만약 주석이 없다면 겁을 먹고 건드리지 않으려 할 수 있다.

 

 

---

 

표시	의미
TODO:	아직 하지 않은 일
FIXME:	오작동을 일으킨다고 알려진 코드
HACK:	문제 있는 해결책(마치 하드코딩?)
XXX:	위험! 여기 큰 문제가 있다는 표시

- 위 표는 주석에 사용되는 표시라고 한다.

 

//TODO: 더 빠른 알고리즘을 사용하라.

//TODO(더스틴): JPEG말고 다른 이미지 포맷도 처리할 수 있어야 한다.

- 이러한 방식으로 사용한다고 한다.

 

---

 

# 이 상수값이 2 * num_processors보다 크거나 같으면 된다.
NUM_THREADS = 8

//합리적인 한계를 설정하라 - 그렇게 많이 읽을 수 있는 사람은 어차피 없다.
const int MAX_RSS_SUBSCRIPTIONS = 1000;

//사용자들은 0.72가 크기/해상도 대비 최선이라고 생각한다.
image_quality = 0.72

- 위 코드는 상수값들 에게 주석을 달아둔 것이다. 

- 상수를 정의할때 종종 그 상수가 무엇을 하는지, 왜 특정값을 가지게 되었는지 '사연'이 존재하기 마련이다.

 

---

정리

- 주석을 다는 목적은 코드를 작성한 사람이 알고 있는 정보를 읽는 사람에게 전달하기 위함이다.

 

1. 설명하지 말아야할 것들

- 코드 자체에서 재빨리 도출 될 수 있는 사실

- 나쁜 함수명을 가진 코드를 보정하려고 '애쓰는 주석' => 이럴꺼면 함수 이름을 수정하라

 

2. 기록해야하는 생각

- 코드가 특정 방식으로 작성된 이유

- 코드에 담긴 결함. TODO, XXX와 같은 표시 사용

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

 

3. 자신을 코드를 읽는 입장에 놓아볼 필요가 있다.

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

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

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

- 코드에 블록별로 주석을 달고 세부 코드를 읽다 숲을 보지 못하는 실수를 저지르지마라