C++ 주석 쓰는 법

/* To generate a random item, we're going to do the following:
 * 1) Put all of the items of the desired rarity on a list
 * 2) Calculate a probability for each item based on level and weight factor
 * 3) Choose a random number
 * 4) Figure out which item that random number corresponds to
 * 5) Return the appropriate item */

C++에서 주석은 // 또는 /*, */를 이용해 다음과 같이 쓸 수 있다.

// your comment goes here

/* This is a multi-line comment.
   This line will be ignored.
   So will this one. */

 

다만, 가독성을 위해 이 주석을 쓰는 규칙 또는 관행이 있다.

---

주석을 쓰는 규칙

 

1. 주석은 Tab stop에 쓰자.

아래 코드와 같이 주석이 tab stop에 정렬되도록 쓰는 것이 가독성이 좋다.

std::cout << "Hello world!\n";                 // std::cout lives in the iostream library
std::cout << "It is very nice to meet you!\n"; // this is much easier to read
std::cout << "Yeah!\n";                        // don't you think so?

 

2. 코드 한 줄이 너무 길다면 코드위에 single-line으로 달자.

// std::cout lives in the iostream library
std::cout << "Hello world!\n";

// this is much easier to read
std::cout << "It is very nice to meet you!\n";

// don't you think so?
std::cout << "Yeah!\n";

 

3. Multi-line comments 가독성 높이는 법

아래 처럼 작성하다면 multi-line comment의 가독성을 높일 수 있다.

/* This is a multi-line comment.
 * the matching asterisks to the left
 * can make this easier to read
 */

 

---

주석을 쓰는 목적 3가지

 

1. 라이브러리, 프로그램, 함수가 어떤 기능을 수행하는지  설명한다.

기능 설명은 코드 첫 줄(가장 위) 또는 함수의 앞에 온다.

Example
// The following lines generate a random item based on rarity, level, and a weight factor.

 

2. 라이브러리, 프로그램, 함수 내에서 코드가 목적 달성을 위해 어떻게 동작하는지 설명한다.

/* To generate a random item, we're going to do the following:
 * 1) Put all of the items of the desired rarity on a list
 * 2) Calculate a probability for each item based on level and weight factor
 * 3) Choose a random number
 * 4) Figure out which item that random number corresponds to
 * 5) Return the appropriate item */

 

3. statement level에서 해당 statement를 왜 그렇게 수행하는 지 또는 statement가 수행되는 이유를 설명한다.

주의할 점은 statement가 무엇을 하는지 설명해서는 안된다.

 

안 좋은 예시

// Set sight range to 0
sight = 0;

좋은 예시

// The player just drank a potion of blindness and can not see anything
sight = 0;

 

안 좋은 예시

// Calculate the cost of the items
cost = quantity * 2 * storePrice;

좋은 예시

// We need to multiply quantity by 2 here because they are bought in pairs
cost = quantity * 2 * storePrice;

 

 

4. 변수 선언 시 변수 설명

// a count of the number of chars in a piece of text, including whitespace and punctuation
int numberOfChars;