Category
Tags

[책요약] 읽기 좋은 코드가 좋은 코드다 5장 주석에 담아야 하는 대상

2020-05-14

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

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

5.1 설명하지 말아야 하는 것

  • 다음 코드에 있는 주석은 모두 가치가 없다.
// 클래스 Account를 위한 정의
class Account {
    public:
        // 생성자
        Account();
        
        // profit에 새로운 값을 설정
        void SetProfit(double profit);
        
        // 이 어카운트의 profit을 반환
        double GetProfit();
}
  • 이러한 주석은 새로운 정보를 제공하거나 코드를 읽는 사람이 코드를 더 잘 이해하도록 도와주지 않으므로 아무런 가치가 없다.

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

# 두 번째 '*' 뒤에 오는 내용을 모두 제거한다.
name = '*'.join(line.split('*')[:2]
  • 기술적으로 보면 이 주석에는 ‘새로운 정보’가 없다.
  • 코드를 읽으면 무슨 일을 수행하는지 알 수 있기 때문이다.
  • 하지만 대부분의 프로그래머는 코드가 아닌 주석을 읽고 코드가 수행하는 일을 훨씬 더 빠르게 이해한다.

설명 자체를 위한 설명을 달지 말라

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

나쁜 이름에 주석을 달지 마라 - 대신 이름을 고쳐라

  • 다음은 언뜻 보기에 CleanReply()라는 함수를 설명하는 것처럼 보이는 주석이다.
// 반환되는 항목의 수나 전체 바이트 수와 같이
// Request가 정하는 대로 Reply에 일정한 한계를 적용한다.
void CleanReply(Request request, Reply reply);
  • 이 주석은 ‘clean’이 의미하는 바를 설명하려고 한다.
  • 이렇게 하는 대신 “한계를 적용한다”는 부분을 애초에 함수명에 포함해야 한다.
// 'reply'가 count/byte/등과 같이 'request'가 정하는 한계조건을 만족시키도록 한다.
void EnforceLimitsFromRequest(Request request, Reply reply);
  • 이 함수명은 전보다 더 ‘스스로 설명하는’ 느낌이 강하다.
  • 좋은 이름은 함수가 사용되는 모든 곳에서 드러나므로 좋은 주석보다 더 낫다.
  • 다음은 이름이 좋지 못한 함수의 또 다른 예다
// 해당 키를 위한 핸들을 놓아준다. 이 함수는 실제 레지스트리를 수정하지는 않는다.
void DeleteRegistry(RegistryKey* key);
  • DeleteRegistry()라는 함수명은 뭔가 위험한 일을 하는 것처럼(레지스트리를 지운다고?) 들린다.
  • ‘이 함수는 실제 레지스트리를 수정하지는 않는다.’라는 주석은 이러한 의심을 완화시키려고 작성되었다.
  • 대신 이름 자체가 정확한 설명을 하는 편이 더 낫다.
void ReleaseRegistryHandle(RegistryKey* key);
  • 일반적으로 사람들은 코드가 가진 나쁜 가독성을 메우려고 노력하는 ‘애쓰는 주석’을 원하지 않는다.
  • 좋은 코드 > 나쁜 코드 + 좋은 주석

5.2 생각을 기록하라

  • 좋은 주석은 단순히 ‘자신의 생각을 기록하는 것’만으로도 탄생할 수 있다.
  • 즉 코딩할 때 생각했던 중요한 생각을 기록하면 된다.

‘감독의 설명’을 포함하라

  • 영화에는 종종 ‘감독의 설명’을 담은 트랙이 있다.
  • 이와 비슷한 방식으로 중요한 통찰을 기록한 주석을 코드에 포함시켜야 한다.
// 놀랍게도, 이 데이터에서 이진트리는 해시테이블보다 40% 정도 빠르다.
// 해시를 계산하는 비용이 좌/우 비교를 능가한다.
  • 이 주석은 코드를 읽는 사람에게 코드를 최적화하느라 시간을 허비하지 않게 도와준다.
// 이 주먹구구식 논리는 몇 가지 단어를 생략할 수 있다. 상관없다. 100% 해결은 쉽지 않다.
  • 이 주석이 없으면 코드를 읽는 사람은 뭔가 버그가 있다고 생각하고 실패를 찾기 위한 테스트케이스를 짜거나, 버그를 수정하는 데 시간을 허비할지도 모른다.
// 이 클래스는 점점 엉망이 되어가고 있다. 어쩌면 'ResourceNode' 하위클래스를
// 만들어서 정리해야 할지도 모르겠다.
  • 이 주석은 코드가 엉망이라는 사실을 밝히고 다른 사람에게 어떻게 수정해야 하는지 알려준다.
  • 만약 이 주석이 없으면 많은 사람들이 이 코드에 겁을 먹어 건드리지 않으려고 할 것이다.

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

  • 코드는 지속적으로 진화하며, 그러는 과정 중에 버그를 갖게 될 수밖에 없다.
  • 이러한 결함을 설명하는 것을 부끄러워할 필요는 없다.
  • 예를 들어 다음과 같이 개선이 필요할 때
// TODO: 더 빠른 알고리즘을 사용하라.
  • 혹은 코드가 불완전할 때
// TODO(더스틴): JPEG말고 다른 이미지 포맷도 처리할 수 있어야 한다.
  • 개선 아이디어를 설명하는게 좋다.
  • 이러한 상황에 프로그래머 사이에서 널리 사용되는 표시가 몇 개 있다.
표시 보통의 의미
TODO: 아직 하지 않은 일
FIXME: 오동작을 일으킨다고 알려진 코드
HACK: 아름답지 않은 해결책
XXX: 위험! 여기 큰 문제가 있다.
TextMate ESC
  • 팀에 따라서 이러한 표시를 사용하는지, 사용한다면 언제 사용하는지 등이 다를 수 있다.
  • 중요한 점은 작성하는 코드의 이러저러한 내용을 훗날 수정할 거라는 생각이 들면, 그러한 생각을 주석으로 작성하는 일은 당연하게 받아들여야 한다는 사실이다.
  • 주석은 코드를 읽는 사람에게 코드의 질이나 상태 그리고 추후 개선 방법 등을 제시하여 소중한 통찰을 제공하기 때문이다.

상수에 대한 설명

  • 상수를 정의할 때는 종종 그 상수가 무엇을 하는지, 그것이 왜 특정한 값을 갖게 되었는지 ‘사연’이 존재하기 마련이다.
NUM_THREAD = 8
  • 별도의 설명이 필요하지 않을 것처럼 보이지만, 이러한 상수값을 선택한 사람은 분명히 뭔가 더 많은 사실을 알고 있을 것이다.
NUM_THREAD = 8   # 이 상수값이 2 * num_processors보다 크거나 같으면 된다.
  • 이제 이 코드를 읽는 사람은 상수값을 어떻게 변경해야 하는지 알게 되었다.
  • 즉 이 값을 1로 하면 지나치게 적고, 50으로 하면 너무 크다는 사실을 알게 된 것이다.
  • 혹은 상수의 특정한 값이 아무런 의미를 갖지 않는 경우도 있다.
  • 이러한 사실을 알려주는 주석도 유용하다.
// 합리적인 한계를 설정하라 - 그렇게 많이 읽을 수 있는 사람은 어차피 없다.
const int MAX_RSS_SUBSCRIPTIONS = 1000;
  • 상수값이 신중하게 설정되었으므로 변경하지 않는게 더 좋은 경우도 있다.
image_quality = 0.72; // 사용자들은 0.72가 크기/해상도 대비 최선이라고 생각한다.
  • 이러한 예를 보면서 여러분은 어쩌면 주석이 필요 없다고 생각했을 수도 있다.
  • 하지만 이러한 주석은 모두 도움이 된다.
  • SECONDS_PER_DAY처럼 어떤 상수는 이름이 매우 명확하므로 주석이 필요없다.
  • 하지만 우리 경험에 따르면 대부분의 상수에 주석을 붙이면 의미가 더 뚜렷해진다.
  • 이렇게 하면 상수에 어떤 값을 설정할 때, 자기가 무슨 생각을 하고 있었는지를 밝히는 것으로 귀결된다.

5.3 코드를 읽는 사람의 입장이 되어라

  • 이 책은 ‘코드를 처음으로 읽는 외부인의 입장에 자기 자신을 놓는 기법’을 다루고 있다
  • 외부인은 여러분의 프로젝트에 여러분만큼 친숙하지 않다.
  • 이 기법은 주석에 들어갈 내용을 찾아낼 때 특히 친숙하다.

나올 것 같은 질문 예측하기

  • 여러분이 작성한 코드를 다른 누군가가 읽는다면 “아니, 이게 뭐 하는 코드야?”라고 생각하는 순간이 있기 마련이다.
  • 바로 그런 부분에 주석을 다는 것이다.
  • 예를 들어 Clear()의 정의가 있다고 하자.
struct Recorder {
    vector<float> data;
    ...
    void Clear() {
        vector<float>().swap(data); // 뭐? 그냥 data.clear()를 호출하지 않는 이유가 뭐지?
    }
};
  • c++ 프로그래머가 이 코드를 읽는다면 대부분이 data를 빈 벡터와 교체하는 대신 그냥 data.clear()를 호출하지 않는 이유를 궁금해 할 것이다.
  • 하지만 이것은 vector가 메모리 할당자에게 자신의 메모리를 실제로 반납하게 하는 유일한 방법이다.
  • 이는 잘 알려지지 않은 c++ 언어 특유의 세부 사항이다.
  • 이 코드에는 다음과 같은 주석이 있어야 했다.
// 벡터가 메모리를 반납하도록 강제한다. ('STL swap trick'을 보라)
vector<float>().swap(data);

사람들이 쉽게 빠질 것 같은 함정을 경고하라

  • 함수나 클래스 문서를 작성할 때 스스로에게 ‘내가 작성한 이 코드를 다른 사람이 읽으면 깜짝 놀랄 만한 부분이 있나? 오용될 수 있나?’ 등의 질문을 던질필요가 있다.
  • 기본적으로 ‘앞질러 생각해서’ 다른 사람들이 여러분의 코드를 사용하다가 만날지도 모르는 문제들을 미리 예측 하는것이다.
  • 예를 들어 사용자에게 이메일을 보내는 함수를 작성했다고 해보자
void SendEmail(string to, string subject, string body);
  • 이 함수를 구현하려면 외부 이메일 서비스에 접속해야 하는데, 이 작업이 1초 이상 걸릴 수도 있다.
  • 웹 애플리케이션을 작성하는 다른 사람이 이러한 사실을 모른채 HTTP 질의를 처리하는 과정에서 이 함수를 호출할지도 모른다.
  • 함수의 ‘세부 사항’을 설명하는 주석으로 이런 종류의 실수를 방지하는게 좋다.
// 외부 서비스를 호출하여 이메일 서비스를 호출한다. (1분 이후 타임아웃된다.)
void SendEmail(string to, string subject, string body);
  • 또 다른 예도 있다.
  • 제대로 작성되지 않은 HTML에 닫기 태그를 삽입하는 FixBrokenHtml() 함수가 있다고 하자.
def FixBrokenHtml(html): ...
  • 이 함수는 대부분 정상적으로 동작한다.
  • 하지만 겹겹으로 중첩되었는데 짝이 맞지 않는 태그가 있으면 엄청난 시간을 허비한다는 함정이 도사리고 있다.
  • 사용자가 이러한 단점을 스스로 깨닫게 하기보다는 주석으로 미리 알려주는게 좋다.
# 실행시간이 0(number_tag * average_tag_depth)이므로 엉망으로 중첩된 입력을
# 사용할 때는 주의해야 한다.
def FixBrokenHtml(html): ...

‘큰 그림’에 대한 주석

  • 팀에 새롭게 합류한 사람들은 ‘큰 그림’을 이해하는 데 어려움을 겪는다.
  • 클래스들이 어떻게 상호작용하고, 전체 시스템에서 데이터가 어떻게 흘러 다니고, 출발점이 어디인지 등을 파악해야 한다.
  • 시스템을 설계하는 사람은 시스템의 구석구석이 모두 자연스럽게 느껴지므로 종종 주석을 달아 내용을 설명해야 한다는 사실을 망각한다.
  • 다음과 같은 상황을 상정해 보자
  • 팀에 새로운 사람이 합류했는데, 그녀는 여러분의 옆 자리에 앉아 있고, 여러분은 그녀가 팀의 코드베이스에 익숙해지게 도와주어야 한다.
  • 여러분은 그녀에게 코드베이스를 개략적으로 보여주면서 특정 클래스나 파일을 가리키고 이렇게 말할지도 모른다.
    • ‘비즈니스 로직과 데이터베이스를 연결해 주는 코드입니다. 애플리케이션 코드에서는 직접 이용하면 안됩니다.’
    • ‘이 클래스는 복잡해 보이지만, 사실 스마트 캐시에 불과합니다. 시스템의 다른 부분은 전혀 모르는 코드에요.
  • 수 분 동안 자연스러운 대화를 나눈 다음에 그녀는 혼자 소스코드를 읽으면서 시스템의 더 많은 내용을 알게 될 것이다.
  • 앞서 설명한 말은 바로 상위수준 주석에 포함되어야 하는 내용이다.
  • 다음은 파일수준 주석에 있어야 하는 설명의 예이다.
// 파일시스템에 편리한 인터페이스를 제공하는 헬퍼 함수들을 담고 있다.
// 파일의 퍼미션과 다른 자세한 세부 사항을 처리한다.

요약 주석

  • 심지어 함수 내부에서 ‘큰 그림’을 설명하는 방식도 좋다.
  • 다음은 더 아래에 있는 하위수준 코드의 내용을 간결하게 요약하는 주석의 예다.
# 고객이 자신을 위해서 구입한 항목을 모두 찾는다.
for customer_id in all_customers:
    for sale in all_sales[customer_id].sales:
        if sale.recipient == customer_id:
            ...
  • 위 예제에서 주석이 없는 상태에서 코드를 한 줄씩 읽는 건 미스터리물을 읽는 행위나 다름없다.
    • (all_customers를 순차적으로 반복하네! 근데 무엇을 위해서지??)
  • 이러한 요약 주석은 몇몇 커다란 ‘덩어리’로 구성된 긴 함수에 특히 유용하다.
def GenerateUserReport():
    # 이 사용자를 위한 lock을 얻는다.
    ...
    # 데이터베이스에서 사용자의 정보를 읽는다.
    ...
    # 정보를 파일에 작성한다.
    ...
    # 사용자를 위한 lock을 되돌려 넣는다.
  • 이러한 주석은 함수가 수행하는 기능의 글머리 요약 역할을 수행하므로, 코드를 읽는 사람은 자세한 내용을 읽기 전에 주석을 보고 요점을 파악할 수 있다.

무엇, 왜, 어떻게 중에서 어느것을 설명해야 하는가?

‘무엇(혹은 어떻게)이 아니라 왜를 설명해라’는 말을 들어 봤을 것이다. 이러한 조언은 그럴듯하게 들리기는 하지만 상황을 지나치게 단순화하고 있으며, 사람에 따라서 다른 의미로 받아 들여지기도 한다. 우리가 하고 싶은 말은, 사람들이 코드를 더 쉽게 읽을 수 있다면 그것이 무엇이든 상관없이 기꺼이 설명하라는 것이다. 그 내용이 무엇, 어떻게, 혹은 왜 (또는 셋 모두) 중에서 어느 것을 포함해도 상관없다.

5.4 마지막 고찰 - 글 쓰는 두려움을 떨쳐내라

  • 많은 프로그래머가 주석 달기를 달가워하지 않는다.
  • 좋은 주석을 창작하기 위해서 시간을 들이는 것을 아깝게 생각하기 때문이다.
  • 이와 같은 ‘글 쓰는 두려움’이 길을 가로 막는다면, 해결책은 그냥 쓰기 시작하는 것뿐이다.
  • 따라서 앞으로 주석 달기를 주저하게 된다면 머릿속에 떠오르는 생각을, 심지어 다듬어지지 않은 생각이라고 해도 일단 쓰기 시작해라.
  • 예를 들어 어느 함수를 작성하는데 ‘이런 제길, 이 리스트 안에 중복된 항목이 있으면 이건 복잡해지잖아’ 라고 생각을 했다면 그냥 그 말을 주석으로 작성하라.
// 이런 제길, 이 리스트 안에 중복된 항목이 있으면 이건 복잡해지잖아
  • 이게 어려운가?
  • 더구나 이것은 그리 나쁜 주석도 아니다.
  • 아무것도 없는 것보다 당연히 더 낫다.
  • 하지만 사용된 단어는 조금 모호하다.
  • 이런 부분을 고치려면 설명을 하나씩 살펴보면서 더 구체적인 표현으로 바꾸면 된다.
    • ‘이런 제길’은 ‘주의: 주의를 기울여야 할 내용’을 의미한다.
    • ‘이건’이라는 표현은 ‘입력을 다루는 코드’를 의미한다.
    • ‘복잡해지잖아’라는 표현은 ‘구현하기 어려워진다’를 의미한다.
  • 그러면 이렇게 새로운 주석으로 다시 태어난다.
// 주의: 이 코드는 리스트 안에 있는 중복된 항목을 다루지 않는다. 그렇게 하는 것이 어렵기 때문이다.
  • 주석을 작성하는 과정을 다음과 같이 아주 간단한 단계르 정리해봤다.
    1. 마음에 떠오르는 생각을 무조건 적어본다.
    2. 주석을 읽고 무엇이 개선되어야 하는지 (그런 부분이 있다면) 확인한다.
    3. 개선한다.
  • 주석을 더 자주 달수록 1번 단계에서 떠오르는 생각의 질이 향상되어 궁극적으로는 수정할 필요가 없게 된다.
  • 주석을 부지런히 자주 작성해야, 나중에 한꺼번에 많은 분량의 주석을 달아야 하는 유쾌하지 않는 상황을 피할 수 있다.

5.5 요약

  • 주석을 다는 목적은 코드를 작성하는 사람이 알고 있는 정보를 코드를 읽는 사람에게 전달하는 것이다.
  • 설명하지 말아야 하는 것
    • 코드 자체에서 재빨리 도출될 수 있는 사실
    • 나쁜 함수명과 같이 나쁘게 작성된 코드를 보정하려고 ‘애쓰는 주석’
      • 그렇게 하는 대신 코드를 수정해라
  • 기록해야 하는 생각
    • 코드가 특정한 방식으로 작성된 이유를 설명해주는 내용 (감독의 설명)
    • 코드에 담긴 결함. TODO: 혹은 XXX:와 같은 표시를 사용하라.
    • 어떤 상수가 특정한 값을 갖게 된 ‘사연’
  • 또한 자신을 코드를 읽는 입장에 놓아볼 필요도 있다.
    • 코드를 읽는 삶이 자기가 작성한 코드의 어느 부분을 보고 ‘뭐라고?’라는 생각을 할지 예측해보고 그 부분에 주석을 추가하라.
    • 평범한 사람이 예상하지 못할 특이한 동작을 기록하라.
    • 파일이나 클래스 수준 주석에서 ‘큰 그림’을 설명하고 각 조각이 어떻게 맞춰지는지 설명하라.
    • 코드에 블록별로 주석을 달아 세부 코드를 읽다가 나무만 보고 숲은 못 보는 실수를 저지르지 마라.

Comments

You May Also Enjoy

자바스크립트 toFixed() 0 없애기

2021-04-26

자바스크립트에서 숫자를 정확한 자릿수로 표현하기 위해 toFixed() 를 사용한다. toFixed() 는 지정한 자릿수보다 짧은 수일 때 뒤를 0으로 채우는데, 경우에 따라서 0을 제거할 경우가 생긴다.

vscode javascript sort import 자동정렬

2021-03-23

코드에 import 를 추가 할 때도, 어느 위치에 넣을지 은근히 신경쓰이기 때문에, 자동으로 정렬해주는 기능을 좋아한다. 여러 방법이 있겠지만, 플러그인을 사용하는 방법과 vscode 설정으로 처리하는 2가지 방법을 적어본다.