Clean Code 4장 - 주석

그동안 개발을 진행하며 내가 짠 코드가 다른 사람에게 더 쉽게 읽히기 바라는 마음으로 주석을 달곤 했다. 하지만 이 책을 읽으며 그것은 괜한 고민이며, 간결한 로직과 분명한 네이밍으로 보완할 수 있음을 알게되었다. 다음은 클린 코드 4장을 정리한 내용이다.

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

코드에 주석을 추가하는 일반적인 이유는 코드의 품질이 나쁘기 때문 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신 난장판을 깨끗이 치우는데 노력하자.

코드로 의도를 표현하라

주석으로 달려는 설명은 함수로 표현할 수 있다.

좋은 주석

1. 법적인 주석
   • 각 소스 파일의 첫머리에 주석으로 들어가는 저작권 정보, 소유권 정보
2. 정보를 제공하는 주석
   • 함수의 반환 값이나, 파라미터 정보
   • 하지만 적절한 네이밍을 통해 극복하기 위해 노력하자.
3. 의도를 설명하는 주석
   • 코드를 작성할 당시의 결정에 깔린 의도를 설명
4. 의도를 명료하게 밝히는 주석
   • 인수나 반환 값이 표준 라이브러리나 변경하지 못하는 코드에 속할 경우 유효하다.
   • 그릇된 주석을 달 위험도 있기에 더 나은 방법이 없는 지 고민하고 정확히 달도록 주의하자.
5. 결과를 경고하는 주석
   • 특정 결과가 테스트하기에 너무 오랜 시간이 걸린다면 이를 경고하는 주석을 남긴다.
6. TODO
   • 앞으로 할일을 남겨두는 것은 좋다.
   • TODO 주석은 주기적으로 점검하여 해결할 것은 빠르게 해결하고 없애도 괜찮은 것은 빠르게 없애는 것이 좋겠다.
7. 중요성을 강조하는 주석
   • 대수롭지 않아 보이는 부분에 중요성을 강조하기 위해서 사용하는 것은 좋다.

나쁜 주석

대다수의 나쁜 주석은 허술한 코드를 지탱하거나, 엉성한 코드를 변병하거나, 미숙한 결정을 합리화하는 프로그래머가 주절거리는 독백에 크게 벗어나지 못한다.

1. 주절거리는 주석 * 특별한 이유없이 의무감으로 다는 주석 * 주석이 이해가 안되어 다른 모듈까지 찾아보게 된다면 다시 신중하게 다시 달도록 한다.
2. 같은 이야기를 중복하는 주석 * 코드와 같은 이야기를 반복하며 코드를 보는 것보다 의미 전달을 못한다면 의미없는 주석이다.
3. 오해할 여지가 있는 주석 * 독자가 잘못 이해할 수 있는 주석 혹은 잘못된 정보를 제공하는 주석 * 해당 코드를 활용하게될 독자가 플로우를 잘못 이해하게 할 수 있다.
4. 의무적으로 다는 주석 * 모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야하는 것은 아니다.
5. 이력을 기록하는 주석 * 요즘은 소스 코드 관리 시스템이 잘 구축되어 있기 때문에 이를 활용하도록한다.
6. 있으나 마나 한 주석 * 너무나 당연한 사실을 제공하는 주석 * 이 주석 또한 단순한 중복일 뿐이다.
7. 위치를 표시하는 주석 * ////////////////// 를 통해 특정 섹션을 나누거나 특정 위치를 나타내는 주석
8. 닫는 괄호에 다는 주석 * 중첩이 심하고 장황한 함수엔 적절할 지 모르나, 우리가 추구하는 짧고 간결하며 캡슐화된 코드엔 필요없다.
9. 공로를 돌리거나 저자를 표시하는 주석 * 이 또한 5번과 같이 소스 코드 관리 시스템이 잘 알려주기에 필요없다.
10. 주석으로 처리한 코드 * 주석으로 처리된 코드는 다른 이로 하여금 ‘이유가 있어 남겨놓았겠지’ 라고 생각하게 하여 지우지 못하게 만든다. * 이러한 것이 쌓이면 결국 쓰레기 덩어리가 쌓이게 되는 것과 같다.
11. HTML 주석 * Javadocs와 같은 도구로 뽑아 웹 페이지에 올릴 작정이라면 HTML 태그를 삽입하는 것은 개발자가 아닌 도구가 처리해야 한다.
12. 전역 정보 * 주석은 근처에 있는 코드에 대한 것만 기록한다. * 전역 함수, 변수에 대한 값이 변경될 경우 어딘가에 떨어져 있을 해당 값의 주석도 변경을 해주어야 독자들에게 정확한 정보를 줄 수 있다. - 관리가 힘들다는 뜻
13. 너무 많은 정보 * 독자가 해당 코드를 사용함에 필요없는 정보는 주석으로 남길 필요가 없다.
14. 모호한 관계 * 주석은 코드로써 설명하기 힘든 것을 설명하는 것이다. * 그렇기에 주석이 다시 설명을 필요로 한다면 나쁜 주석이다.
15. 함수 헤더 * 짧은 함수는 긴 설명이 필요없다. * 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.
16. 비공개 코드에서의 Javadocs * 공개 API 에서는 Javadocs가 유용하지만, 시스템 내부의 클래스와 함수엔 필요없다.

결국 앞선 장에서 설명한 것처럼 클래스, 함수, 변수의 이름이 명확하다면 이러한 불필요하고 오해의 소지가 있는 주석은 사라질 수 있을 것이다. 또한 함수가 한 가지의 역할만을 하고 짧고 간결하게 만들어져 있다면 주석을 달지 않아도 독자들이 이해하기 쉬울 것이다. 만약 코딩을 하며 주석이 필요하다고 느껴질 경우 네이밍이 안좋은 것은 아닌지 다시 확인해보고, 함수를 세분화할 수 있을 지 확인해봐야겠다.