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

🔥해당 글은 프로젝트 팀원과 함께 프로젝트 퀄리티 및 더 나은 개발자가 되기 위하여 북 스터디를 진행하였습니다.

• 나쁜 코드
  • 나쁜 코드에 주석을 달지 마라. 새로 짜라
  • 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다.
  • 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 피해를 준다.
• 좋은 코드
  
  • 잘 달린 주석은 그 어떤 정보보다 유용하다.
  • 코드만이 정확한 정보를 제공하는 유일한 출처다.
  • 프로그래밍 언어를 잘 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않다.
• 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다.
• 그러므로 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

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

• 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.
• 주석으로 설명하려는 시간을 쓰는 대신 깨끗하게 구현하는데 시간을 보내는 것이 좋다.

코드로 의도를 표현하라!

• 코드만으로 의도를 설명하기 어려운 경우가 존재한다.
• 그래도 코드에 개발자의 의도를 표현하는 방법을 사용해야 한다.
  • 의미를 확실하게 전달할 수 있게 함수로 만들어서 표현해도 충분하다.

좋은 주석

• 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.

법적인 주석

• 때로는 회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣으라고 명시한다.
• 각 소스 파일 첫머리에 들어가는 주석이 반드시 계약 조건이나 법적인 정보일 필요는 없다.
• 모든 조항과 조건을 열거하는 대신에, 가능하다면, 표준 라이센스나 외부 문서를 참조해도 된다.

정보를 제공하는 주석

• 기본적인 정보를 주석으로 제공하는 편리하다 할지라도, 함수 이름에 정보를 담는 편이 더 좋다.

의도를 설명하는 주석

• 때때로 주석은 구현을 이해하기 도와주는 선을 넘어 결정에 깔린 의도까지 설명한다.

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

• 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
• 주석이 올바른지 검증하기 쉽지 않기 때문에, 의미를 명료히 밝히는 주석이 필요한 이유인 동시에 위험한 이유일 수 있다.
• 그러므로 주석을 달 때는 더 나은 방법이 없는지 고민하고 정확하게 달도록 각별하게 주의해야 한다.

TODO 주석

• '앞으로 할 일'을 //TODO 주석으로 남겨두면 편하다.
• 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다.
• 더 이상 필요 없는 기능을 삭제하라는 알림, 누군가에게 문제를 봐달라는 요청, 더 좋은 이름을 떠올려달라는 부탁, 앞으로 발생할 이벤트에 맞춰 코드를 고치라는 주의 등에 유용하다.
• 하지만 어떤 용도로 사용하든 시스템에 나쁜 코드를 남겨 놓는 핑계가 되어서는 안 된다.
• 요즘 나오는 대다수 IDE는 TODO 주석 전부를 찾아 보여주는 기능을 제공하므로 주석을 잊어버릴 염려는 없다.
• 그래도 TODO로 떡칠한 코드는 바람직하지 않다. 그러므로 주기적으로 TODO 주석을 점검해 없애도 괜찮은 주석은 없애라고 권한다.

공개 API에서 Javadocs

• 공개 API를 구현한다면 반드시 훌륭한 Javadocs를 작성한다.
• 어느 주석과 마찬가지로 Javadocs 역시 독자로 오도하거나, 잘못 위치하거나, 그릇된 정보를 전달할 가능성이 존재한다.

나쁜 주석

• 대다수의 주석이 나쁜 주석이다.
• 일반적으로 대다수 주석은 허술한 코드를 지탱하거나, 엉성하거나, 미숙한 결정을 합리하는 등 좋지 못한다.

주절거리는 주석

• 특별한 이유 없이 주석을 단다면 시간낭비일 뿐이다.
  • 그래도 주석을 달기로 결정했다면 충분한 시간을 들여서 최고의 주석을 달도록 노력해야 한다.
• 이해가 안 돼서 다른 모듈까지 확인해야 하는 주석은 바이트만 낭비하는 주석일 뿐이다.

같은 이야기를 중복하는 주석

• 주석이 코드보다 더 많은 정보를 제공하지 못한다.
• 실제로, 코드보다 정확하지 못해 함수를 대충 이해하고 넘어가게 만든다.
• 쓸모없고 중복되는 주석은 코드만 지저분하게 만들고 정신없게 만든다. 

오해할 여지가 있는 주석

• 코드보다 읽기 어려운 주석에 담긴 잘못된 정보에 의해 프로그래머가 실수를 할 수도 있다.
• 의도는 좋으나 프로그래머에게 완벽하게 전달될 정도로 주석을 달지 못하기도 하기 때문이다.

의무적으로 다는 주석

• 모든 함수 또는 모든 변수에 주석을 달아야 한다는 규칙은 코드를 복잡하게 만든다.
• 오히려 코드만 헷갈리게 만들고, 잘못된 정보를 제공할 여지만 만든다.

이력을 기록하는 주석

• 깃과 같은 소스 코드 관리 시스템이 있기 때문에, 소스에 주석으로 이력을 기록하는 것은 이제 불필요하다.

있으나 마나 한 주석

• 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석이다.
• 있으나 마나 한 주석을 달려는 유혹을 벗어나고 코드를 정리하는 게 좋은 프로그래머가 되는 길이다.

함수나 변수로 표현할 수 있다면 주석을 달지 마라

• 주석이 필요하지 않도록 코드를 개선하는 편이 좋다.

위치를 표시하는 주석

• 때때로 프로그래머는 소스 파일에서 특정 위치를 표시하려 주석을 사용한다.
• 일반적으로 이러한 주석은 가독성만 낮추기 때문에 제거하는 것이 좋다.
• 특히, 뒷부분에 슬래시(/)로 이어지는 잡음은 제거하는 편이 좋다.

닫는 괄호에 다는 주석

• 때때로 프로그래머는 닫는 괄호에 특수한 주석을 사용한다.
• 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 함수를 줄이는 것이 좋다.

공로를 돌리거나 저자를 표시하는 주석

• 이러한 정보는 소스 코드 관리 시스템에 저장하는 편이 좋다.

주석으로 처리한 코드

• 주석으로 처리한 코드만큼 안 좋은 것도 없다.
• 주석으로 처리된 코드는 다른 사람들이 이유가 있을 테니 지우기를 주저한다.
• 계속해서 쓸모없는 코드만 점차 쌓여간다.

HTML 주석

• 소스 코드에서 HTML 주석은 혐오 그 자체다.

너무 많은 정보

• 주석에다 흥미로운 역사나 관련 없는 정보를 작성하는 것은 좋지 않다.

함수 헤더

• 짧은 함수는 긴 설명이 필요 없다.
• 짧고 한 가지만 수행하여 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.

비공개 코드에서 Javadocs

• 공개 API는 Javadocs가 유용하지만, 공개하지 않을 코드라면 Javadocs는 쓸모가 없다.
• 시스템 내부에 속한 클래스와 함수에 Javadocs를 생성할 필요는 없다.
• 유용하지 않을 뿐만 아니라 Javados 주석이 요구하는 형식으로 인해 코드가 보기 싫고 산만해진다.