좋은 주석, 나쁜 주석_CleanCode_70p

 

 

하지만 명심하기 바란다.
정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!

_cleancode 70p 중

 

주석 챕터에 들어오면서 처음 개발 공부하면서 빌드했던 개념들이 와르르 무너지게 되었다.

 

주석을 사용하면 마냥 좋은 줄 알고 남발했던 모든 주석이

사실은 가독성을 해치며 코드를 읽는 이로 하여금 오해하게 만드는 주석이었다니..

 

---

 

🍎 좋은 주석

책에서 소개하는 좋은 주석의 사레는 법적인 주석, 정보를 제공하는 주석, 의도를 설명하는 주석, 의미를 명료하게 밝히는 주석, 결과를 경고하는 주석, TODO 주석, 중요성을 강조하는 주석 등이 있다.

 

책에서는 이런 좋은 주석들도 가능하면 함수 이름이나 클래스를 만드는 등 코딩적인 방법을 이용해서 주석을 사용하지 않을 수 있으면 더 좋다고 얘기하고 있다. 

 

 

내용 중 와닿았던 부분은 읽는 이로 하여금 작성자의 고민과 의도, 꼭 알아야 할 중요한 정보나 경고를 주석으로 남기는 것이었다. 

 

작성자가 문제를 해결한 방식에 동의하지 않을지도 모르지만 그 의도는 분명하게 드러나는 주석. 이런 주석이 좋은 주석이다.

 

🍎 나쁜 주석

나쁜 주석의 사례로는 주절거리는 주석, 같은 이야기를 중복하는 주석, 오해할 여지가 있는 주석, 의무적으로 다는 주석, 이력을 기록하는 주석, 있으나 마나 한 주석, 위치를 표시하는 주석, 닫는 괄호에 다는 주석 등등등이 있는데 대부분의 주석은 여기 해당한다고 한다.

 

타이틀만 읽어보면 '당연히 이런 주석은 안좋지'라고 생각하게 된다. 하지만 실제로 이러한 주석들이 많이 사용되고 있으며 처음 개발 공부할 때는 이런 주석을 권장하는 것을 여러 번 듣기도 했다. 

 

 

나도 이런 나쁜 주석을 양산하고 있다고 생각하니 멍해짐을 뒤로하고 잠시 고민을 해보았다. 

 

생각해보니 코드를 작성하는 데는 공을 들이고 리팩토링도 진행하며 완성도를 높이려고 하지만 주석을 잘 쓰기 위해서는 별로 노력하지 않았다. 

 

이런 주석들이 쌓이다 보면 코드를 읽는데 많은 시간이 소요되고 불필요한 잡음이 들어가 오해의 여지가 생길 수 있으니 주석을 작성할 때도 신중하게 작성해야 한다.

 

 

---

 

코드를 읽을 다른 사람을 위해 배려하는 마음으로 쓰는 좋은 주석은 읽는 이로 하여금 기분 좋은 향을 느끼게 한다.

 

오늘도 개선할 점을 찾았다.