> For the complete documentation index, see [llms.txt](https://simian114.gitbook.io/blog/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simian114.gitbook.io/blog/undefined-1/odds_and_ends/undefined/clean_code/chapter4..md).

# Chapter4. 주석

주석을 달 시간에 어떻게 코드를 더 잘 표현할지에 대해 고민하자.

## 4.0 주석은 필요악이다.

* 분명 좋은 주석도 있다. 하지만 우리의 주석은 보통의 경우 `나쁜 주석`일 가능성이 높다. 
* 주석을 다는 이유를 생각해보자. 나의 경우를 생각해보면 내가 작성한 코드를 상대방이 내가 의도한 대로 이해하기를 바라는 마음에 적는 경우가 많았다. 처음부터 다른 사람이 읽었을 때 의도한 대로 코드를 이해할 수 있게 작성해야 하는데 나는 그렇지 못했던 것이다.
* 또한 주석은 변화하는 코드에 따라가지 못하는 경우가 많다. 이것또한 많은 사람이 공감할 이야기라 생각한다. 혼자가 아닌 팀이 하는 프로젝트에 주석을 하나 달아 놓으면 그 주석은 미아가 되어버리는 경우가 많다.

## 4.1 주석은 나쁜 코드를 보완하지 못한다.

* 코드에 주석을 추가하는 일반적인 이유는 ***코드의 품질이 나쁘기 때문이다***
* 만약 코딩을 하다 `아 주석을 달아야 겠다!` 라는 생각이 들면 절대 주석을 달면 안된다.
  * ***코드를 정리해야한다.***
* 표현력이 풍부하고 깔끔하며 주석없는 코드가 주석이 여럿 달린 코드보다 훨씬 좋다.
* 자신이 저지른 난장판을 주석으로 설명하려 애쓰지 말고 난장팡을 깨끗이 치우는데 시간을 쓰자!

## 4.2 코드로 의도를 표현하라

* 분명 코드만으로 의도를 설명하기 어려운 경우가 존재한다. 하지만 시간을 들이면, 생각을 조금 더 해보면 분명히 코드로 대다수 의도를 표현할 수 있을 것이다.

## 4.3 좋은 주석

> 좋은 주석은 필요하거나 유익하다. 단 명심하라 우수한 주석은 달지 않을 방법을 찾아낸 주석이라는 사실을!

### 4.3.1 법적인 주석

* 법적인 내용, 저작권 소유권 정보는 필요하다.

### 4.3.2 정보를 제공하는 주석

* 기본적인 정보를 제공하는 주석인 편리하다. 주로 테스트 케이스에서 의미가 있다.

### 4.3.3 의도를 설명하는 주석

* 표현력이 풍부한 이름을 가진 함수가 있다고 해도 만약 코드를 같이 공유하지 않는 사람이 본다면 헷갈릴 여지는 충분히 있다. 이럴때는 코드의 의도를 설명하는 주석을 달면 좋다.
* 이미 표현력이 풍부한 함수였고 저자의 의도까지 설명이 되어있다면 코드를 처음보는 사람도 충분히 이해할 수 있을 것임.

### 4.3.4 의미를 명료하게 밝히는 주석

* 때때로 애매한 인수나 반환 값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.
* 물론 우리가 직접 작성하는 함수들은 앞서 이야기한 부분을 다 표현력있게 해야한다.
* 단, 우리가 작성한 코드가 아니라 `표준 라이브러리` 와 같이 이미 만들어져 있는 무언가를 사용할 때는 인수나 반환값이 애매할 때가 존재한다. 이런 경우에 주석을 달아서 그 의미를 명확하게 하는건 좋은 주석이다.

### 4.3.5 결과를 경고하는 주석

* 다른 프로그래메어게 결과를 경고할 목적으로 주석을 사용한다.
* 예를 들면 코드의 실행 결과로 무엇인가 `삭제` 되거나 `수정` 되는 경우, 또는 실행시간이 매우 긴 경우가 있다.

### 4.3.6 TODO 주석

* `앞으로 할 일`을 `//TODO` 주석으로 남겨두면 좋다.
* 주의할 점은 `//TODO` 주석을 남겨놓고 너무 오랫동안 방치하는건 좋지 않다.
* 수시로 `TODO` 주석을 점검하는 습관을 들이자

### 4.3.7 중요성을 강조하는 주석

* 자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위한 주석

## 4.4 나쁜 주석

* 대다수 주석이 이 범주에 속한다.

### 4.4.1 주절거리는 주석

* 특별한 이유 없이 의무감으로 혹은 작업 프로세서에서 하라고 하니까 마지못해 다는 주석을 절대로 시간낭비다.
  * 만약, 주석을 무조건 달아야하는 상황이라면 ***충분한 시간을 들여서 최고의 주석*** 을 만들자.

### 4.4.2 같은 이야기를 줒ㅇ복하는 주석

* 이미 표현력이 충분한 함수를 만들어 놓았는데, 그 함수에 굳이 주석을 달아서 함수를 설명할 필요는 없다.
* 이런 주석은 함수보다도 더 많은 정보를 제공하지 못한다.

### 4.4.3 오해할 여지가 있는 주석

* 정확하지 않는 주석은 정말 최악이다...

## 나쁜 주석은 너무 많아서 이하는 생략한다. 결론은 왠만하면 주석을 달 시간에 어떻게 더 표현력 있게 코드를 작성할지를 고민하자.