주석을 잘쓰는 방법 : 주석에 담아야하는 내용 (1/2)

  업무를 하면서 프로그램을 짜다가 주석을 쓸 때가 많습니다. 그런데, 이 때 이 후에 내가 보았을 때 도움이 되거나 동료가 이 코드를 보았을 때 도움이 되도록 잘 적으려면 어떻게 무엇을 적어야할 지 막막할 때가 많습니다. 책을 읽다가 이런 상황에서 도움을 줄만한 내용이 있어 발췌하여 정리합니다.

아래 내용은 '읽기 좋은 코드가 좋은 코드다 - The Art of Readable Code' 의 주석에 담아야하는 대상 챕터를 읽고 정리한 내용 입니다.

---

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

따라서 가치없는 주석도 있다. 

적지 말아야할 주석

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

// 주어진 이름과 깊이를 이용해서 서브르리[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)

2. 나쁜이름에 주석을 달지마라. -> 이름을 고쳐라

// 반환되는 항목의 수나 전체 바이트 수와 같이 

// Request 가 정하는 대로 Reply에 일정한 한계를 적용한다.

void CleanReply(Request request, Reply reply)

-> Request 가 정하는 대로 한계를 적용한다. 는 부분을 애초에 함수명에 포함한다면 주석을 달지 않아도 된다.

    아래 함수명은 함수명 자체가 스스로 설명하는 느낌이 강하다.

void EnforceLimitsFromRequest(Request request, Reply repley)

무엇을 설명해야하는가?

1. 생각을 기록하라.

  개발 시 중요한 통찰을 기록해야한다.

// 놀랍게도, 이 데이터에서 이진트리는 해시 테이블보다 40% 정도 빠르다.

// 해시를 계산하는 비용이 좌우 비교를 능가함.

-> 이 주석을 읽으면  이코드는 최적화가 불필요함을 바로 알 수 있다.

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

-> 이 주석이 없으면 이코드를 읽는 사람은 버그가 있는 줄 알고 실패를 찾기 위한 테스트 케이스를 자거나 버그를 수정하는데 시간을 쓸지 모른다.

    하지만 이 주석을 통해 이 코드는 지금 상태로도 괜찮다는 것을 알 수 있다.

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

-> 이 주석은 다른 사람에게 어떻게 수정해야 할지 가이드를 제시해준다.

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

  훗날 수정할 거라는 생각이 드는 부분이 있으면 이러한 생각을 주석으로 작성해두는 것이 좋다.

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

// TODO : Jpeg말고 다른 이미지 포맷도 처리할 수 있어야한다.

  TODO: 아직하지 않은일

  FIXME: 오동작을 일으킨다고 알려진 코드

  HACK:  아름답지 않은 해결책

  XXX: 위함! 여기 큰 문제가 있다.

  TextMate: ESC

3. 상수에 대한 설명

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

-> 상수를 어떤 식으로 변경해야하는 지 알 수 있다.

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

-> 상수가 최적임을 알고 변경을 자제해야함을 알 수 있다.