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

이 글은 아래 글에서 이어지는 글이며, '읽기 좋은 코드가 좋은 코드다 - The Art of Readable Code' 에서 발췌했습니다.

이전글 : 

2017/12/19 - [Study] - 주석을 잘쓰는 방법 : 주석에 담아야하는 내용 (1/2)

---

아래 내용들은 주석에 들어갈 내용을 찾아낼 때 유용하게 쓰일 수 있다.

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

1. 나올것 같은 질문예측하기

  작성한 코드를 읽고 뭐하는 코드인지 궁금해 할 것 같은 부분에 주석을 적는다.

struct Recorder {

vector<float> data;

...

void Clear() {

// 벡터가 메모리를 반납하도록 강제한다. ("STL swap trick" 을 보라.)

  -> 코드를 보고 왜 data.clear()를 호출하지 않고 빈데이터와 swap 하는 지 궁금할 것이다. 

     이는 vector가 메모리 할당자에게 자신의 메모리를 실제로 반납하게 하는 유일한 방법. C++ 의 특유사항이다.

vector<float>().swap(data);

}

}

2. 사람들이 빠질 것 같은 함정을 경고

// 외부 서비스를 호출하여 이메일 서비스를 호출한다. (1분 이후 타임아웃된다.)

  -> 외부 서비스로 이메일 서비스를 호출하기 때문에 느릴 수도 연결타임이 발생할 수 있음을 예측할 수 있고, 타임아웃시간이 1분 임을 알 수 있다.

void SendEmail(string to, string subject, string body);

// 실행시간이 0(nuber_tags * average_tag_depth)이므로 엉망으로 중첩된 입력을 사용할 때는 주의 할 것.

  -> 제대로 작성되지 않은 HTML 에 닫기 태그를 삽입하는 함수이지만, 겹겹의 중첩된 태그에서는 시간이 많이 걸린다는 것을 알 수 있다.

def FixBrokenHtml(html);

3. 큰그림을 알려주는 주석

코드 베이스를 개략적으로 보여주는 주석으로써, 보통 특정클래스나 파일의 처음에 주로 작성된다.

상위수준 주석의 예

// 비지니스 로직과 데이터 베이스를 연결해주는 코드. 애플리케이션 코드에서는 직접이용하면 안됨.

// 아래 클래스는 스마트 캐시 임. 시스템의 다른 부분은 전혀모르는 코드.

파일수준 주석의 예

// 파일시스템에 편리한 인터페이스를 제공하는 헬퍼함수들을 담고 있다.

// 파일의 퍼미션과 다른 자세한 세부사항을 처리한다.

또는, 하위수준 코드의 내용을 간결하게 요약한 내용을 주석으로 적어, 함수 동작의 큰그림을 설명할 수도 있다.

// 고객이 자신을 위해 구입한 항목 모두를 찾는다.

for customer_id in all_customers:

for sale in all_sales[customer_id].sales:

if sale.recipient == customer_id:

몇몇 덩어리로 이루어진 긴 함수의 경우는 덩어리별로 요약 주석을 달아서 이해를 돕는다.

def GenerateUserReport():

# 이 사용자를 위한 lock를 얻는다.

...

# 데이터베이스에서 사용자의 정보를 얻는다.

...

# 정보를 파일에 작성한다.

...

# 사용자를 위한 lock를 되돌려놓는다.

글을 쓰는 두려움을 떨쳐라.

코드를 쉽게 이해할 수 있도록 해야겠다고 생각이 들거나 주석을 적어야 겠다고 생각이 들면 일단 떠오르는 생각을 그냥 적는다.

그리고, 적은 주석을 보고 무엇이 개선되어야하는지 확인하고 개선하는 작업을 반복한다.

주석을 부지런하게 작성해봐야 주석을 작성하는 실력이 늘어난다.

그리고, 주석을 그때 그때 작성해야 한꺼번에 몰아서 작성하는 폐혜를 막을 수 있다.