[클린 코드] #4 주석

클린 코드 #4 주석

#클린코드

잘 달린 주석은 정말 유용하지만, 잘못 달린 주석은 독이다.
우리가 코드를 잘 짰다면 사실 주석은 거의 필요가 없다. 코드로 의도를 표현하지 못해서 주석을 사용하는 것이다.

주석은 오래될 수록 코드에서 점점 멀어진다. 코드를 유지보수하면서 주석까지 유지 보수하기는 현실적으로 불가능하다. 점점 더 주석과 코드가 분리되버린다.

주석을 엄격하게 관리해야 하지만, 코드를 깔끔하게 정리하는 대에 더 많은 신경을 쓰는게 좋다.

코드만이 진실을 이야기한다.

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

난장판을 주석으로 표현하지 말고, 난장판을 치우는데에 시간을 써라.

코드로 의도를 표현하라.

조금만 더 생각하면 코드로 대다수 의도를 표현할 수 있다. 주석으로 달려는 설명을 차라리 함수로 만들어서 표현해도 충분하다.

좋은 주석

정말로 어떤 주석은 필요하거나 유익하다. 근데 이런 주석은 몇 케이스가 없다.

법적인 주석

회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣어야 하는 경우
예를 들면, 소스 첫 줄에 주석을 넣어 계약 조건이나 법적 정보, 표준 라이선스 등을 표시하는 경우이다.

정보를 제공하는 주석

때로는 기본적인 정보를 주석으로 제공하면 편리하다.

// 테스트중인 Responder 인스턴스를 반환한다.
protected abstract Responder responderInstance();

유용해보일지라도, 함수 이름에 정보를 담자. responderBeingTested로 바꾸면 주석이 필요없다.

정규 표현식이 나타내는 형식이 있다면, 주석으로 설명하는 것 보단 형식 세부적인 것을 변환 클래스로 만들어서 코드로 옮겨주는 것이 깔끔하다.

의도를 설명하는 주석

때로는 주석이 구현 이해를 도우는 선을 넘어 구현 의도까지 설명한다.

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

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

물론 그릇된 주석을 달아놓았을 위험이 있다. 검증하는 것도 쉽지 않다. 최대한 주석을 달지 않을 방법을 고민하고, 주석을 단다면 각별히 주의해서 달아야 한다.

결과를 경고하는 주석

예를 들면, 특정 테스트 함수가 너무 오래걸린다면, 주석으로 시간이 없다면 테스트 실행하지 마라고 적어둘 수 있다. 실수를 면하는 용도로 사용할 때 주석이 합리적일 수 있다.

TODO 주석

학부 수업을 듣거나, 부트 캠프 미션을 수행하거나 여러 코딩 관련 미션, 과제를 수행할 때 TODO 주석은 정말 많이 볼 수 있을 것이다. 이러한 TODO 주석은 유용하다.

하지만 어떤 용도로 TODO 주석을 사용하든 시스템에 나쁜 코드를 남겨 놓는 핑계가 되어서는 안 된다.
그리고 주기적으로 TODO 주석을 점검해서 없앨 수 있으면 없애주자.

중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 강조하기 위해 주석을 사용할 수 있다.

공개 API에서 Javadocs

우리가 API 문서 Javadocs를 볼 때 주석이 잘 정리되어 있는 것을 볼 수 있다.
공개 API를 구현할 때는 Javadocs를 정말 잘 작성해야 한다. Javadocs 역시 독자를 오도하거나 그릇된 정보를 전달할 가능성이 존재하기 때문이다.

나쁜 주석

대부분 주석이 나쁜 주석이다. 코드를 변명하는 용도로 쓰이는 것이다.

주절거리는 주석

누군가 시키거나 의무감으로 주석을 달라고 한다면, 최선을 다해서 주석을 달아라, 대충 달면 시간 낭비에 독자에게 그릇된 정보를 줄 수 있다.

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

가끔가다 함수 헤더(선언부)에 달린 주석이 코드의 내용을 설명하고 있는 것을 볼 수 있을 것이다. 하지만 주석보다 코드가 더 많은 정보를 제공한다. 이런 주석은 코드를 변명하는 용도일 가능성이 높다. 오히려 코드보다 부정확해 독자가 함수를 대충 이해하게 만들어버린다.

오해할 여지가 있는 주석

코드가 주석보다 더 많은 정보를 제공한다. 주석에 살짝 잘못된 정보를 담아버리면, 독자가 함수를 호출할 때 실수해버릴 수도 있다. 호출하는 사람이 원인을 찾지 못하고 헤맬 수 있는 것이다.

의무적으로 다는 주석

예를 들어 모든 함수에 Javadocs를 넣으라는 이상한 의무적인 규칙이 있다면, 이는 잘못된 정보를 제공할 여지를 만들어버린다.

이력을 기록하는 주석

모듈을 편집할 때 마다 모듈 첫머리에 변경을 모두 기록하는 로그를 주석으로 남기는 사람들이 있다.
이제는 IDE가 로그를 알아서 다 남겨준다. 만약 이런 주석이 있다면 완전히 제거하자.

있으나 마나 한 주석

너무 당연한 사실을 적어서 새로운 정보를 제공하지 못하는 경우이다. 이런 주석은 오히려 독자에게 주석을 건너띄고 읽게 유도해버릴 수 있다.

무서운 잡음

목적이 없이 단순히 Javadocs 를 제공하겠다는 욕심으로 주석을 달지 마라.

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

주석이 필요하지 않도록 코드를 개선하는게 좋다.
주석을 먼저 달고 주석에 맞춰 코드를 작성하면 코드에 의도가 명확히 드러나지 않을 수 있다.

위치를 표시하는 주석

특정 위치를 표시하기 위해 주석을 사용하는 경우도 있다.

// Actions //////////////////////////////

특정 코드를 너무 자주 사용하지 않는다면 배너같은 주석을 아주 드물게 사용할 수는 있다. 하지만 이런 배너를 남용하면 잡음이 되어 독자가 무시하게 된다.

닫는 괄호에 다는 주석

닫는 괄호에 주석을 달아야겠다는 생각이 들면, 함수를 줄이려고 시도하자.

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

요즘은 VCS를 통해서 누가 뭐를 추가했는지 바로 알 수 있다. 이를 주석으로 표현하지 말자.

주석으로 처리한 코드

다른 사람이 보기에 뭔가 이유가 있으니까 주석으로 코드를 남겨놨을거라 생각하고 지우지 않는다. 코드를 주석으로 처리하면 점점 이런 것만 쌓여버리게 된다.

보통 이렇게 주석으로 코드를 처리하는 이유는, 변경 사항을 놓치지 않기 위해서 사용하는 경우가 많다. 하지만 이제는 VCS가 변경 내역을 관리해준다. 주석으로 처리하지말고 그냥 코드를 삭제해라.

HTML 주석

그냥 읽기가 어렵다.

전역 정보

주석을 달아야 한다면 근처에 있는 코드만 기술하라. 코드 일부에 주석을 달아서 시스템 전반적인 정보를 기술하지 마라.

너무 많은 정보

주석에 불필요하거나 관련없는 정보를 장황하게 늘여놓지 마라.

모호한 관계

주석이 코드를 명확하게 설명해야 한다. 주석과 코드 사이의 관계가 명백해야 한다는 것이다.

함수 헤더

코드를 짧게 작성한다면, 함수 헤더에 주석을 작성할 일이 없어진다.

비공개 코드에서 Javadocs

공개하지 않을 코드라면 Javadocs는 쓸모가 없다. 오히려 시스템 내부의 코드들은 Javadocs에 의해 지저분해질 뿐이다.