[Clean Code] 클린 코드 - 4장 주석

잘 달린 주석은 유용하지만 사실 프로그래밍 언어를 사용해서 코드 설명을 잘할 수 있는 능력이 있다면, 주석은 필요하지 않다. 

"내가 이렇듯 주석을 무시하는 이유가 무엇이냐고? 거짓말을 하니까. 항상도 아니고 고의도 아니지만 너무 자주 거짓말을 하니까."

라고 표현할 정도로 저자는 주석은 불필요한 존재라 말한다. 그 이유는 코드는 계속 변화하는데, 주석은 오래될수록 코드에 대한 설명을 잘 해내지 못하며 프로그래머들이 이 주석들을 유지 보수하기는 어렵기 때문이다.

그리하여 저자는 주석이 필요 없도록 코드를 깔끔하게 정리하는 것에 에너지를 쏟겠다고 말한다.

 

부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다. ˙˙˙ 진실은 한곳에만 존재한다. 바로 코드다.

 

 

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

일반적으로 주석을 추가하는 이유는 코드가 복잡하다고 생각하기 때문이므로 그 코드를 보다 좋게 만드는 것에 시간을 쏟는 것이 바람직하다.

 

코드로 의도를 표현하라!

주석으로 쓰려고 했던 설명을 함수로 만드는 등 조금의 시간을 들여서 코드로 의도를 표현하도록 해야 한다.

 

좋은 주석(가장 BEST는 주석을 사용하지 않는 것!)

- 법적인 주석 : 소스 파일 첫머리에 들어가는 저작권 정보 & 소유권 정보는 주석

- 정보를 제공하는 주석 : 추상 메서드가 반환할 값을 설명하거나 정규표현식의 시각과 날짜 형식을 설명하는 등의 기본적인 정보들을 제공할 수 있으나 함수 이름을 바꾸거나 클래스를 만드는 등의 방법으로 바꾼다면 더 좋다.

- 의도를 설명하는 주석 : 코드 작성의 의도를 설명할 수 있겠다.

- 의미를 명료하게 밝히는 주석 : 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 있다면 주석을 유용하게 활용할 수 있다.

- 결과를 경고하는 주석 : 특정 테스트 케이스를 꺼야 하는 이유(@Ignore을 사용하면 되기는 한다) 등을 알리기 주석을 사용하여 큰 실수를 피할 수 있다.

- TODO 주석 : 필요하지만 당장은 구현하기 어려운 부분에 대해서 기록할 수 있다.

- 중요성을 강조하는 주석 : 타인에게 중요하지 않아 보일 무언가의 중요성을 드러내기 위해서 사용할 수 있다.

- 공개 API에서 Javadocs → /** contents */

 

나쁜 주석(대다수)

주절거리는 주석, 같은 이야기를 중복하는 주석, 오해할 여지가 있는 주석, 의무적으로 다는 주석, 이력을 기록하는 주석, 있으나 마나 한 주석, 무서운 잡음(때때로 Javadocs도 포함), 함수나 변수로 표현할 수 있다면 주석을 달지 마라, 위치를 표시하는 주석, 닫는 괄호에 다는 주석, 공로를 돌리거나 저자를 표시하는 주석, 주석으로 처리한 코드, HTML 주석, 전역 정보, 너무 많은 정보, 모호한 관계, 함수 헤더, 비공개 코드에서 Javadocs

이렇게 여러 유형의 주석들을 사용하지 않도록 주의해야겠다.

 

---

느낀점

사실 코딩을 잘하지 못하고 코딩에 자신이 있지도 않아서 코드가 길게 작성될 일이 없다. 주석을 사용하는 경우는 알고리즘을 풀고 설명을 덧붙일 때 정도이다. 또는 다른 사람의 코드를 분석하며 기억하거나 스스로의 이해를 돕기 위해서 사용하곤 한다. 그렇지만 나 또한 코드로 충분히 설명되는 것들을 주석으로 표현하는 등의 저자가 싫어할(?)만 한 코딩을 했던 것 같다. 앞으로는 주석도 의미 있게 사용하는 그런 사람이 되겠어..!​

 

TIL 6회차