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 오해할 여지가 있는 주석

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

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