Clean Code - 4장 - 주석

Whale·2023년 3월 17일
0

CleanCode

목록 보기
4/6

나쁜 코드에 주석을 달지 마라. 새로짜라.
브라이언 W. 커니핸.P.J.플라우거

주석은 유용하지만 경솔하고, 근거없는 주석은 코드를 이해하기 어렵게 만든다.
주석은 대부분 필요 없다. 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않다. 대부분의 주석이 표현할 방법을 찾지 못해 사용될 뿐이다.

코드는 변화하고 진화한다. 계속해서 개선되지만 불행히도 주석은 코드를 따라가지 못한다. 부정확한 고어로 변하는 사례가 너무도 흔하다. 부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘며, 코드만이 정확한 정보를 제공하는 유일한 출처다.

그러므로 우리는 (간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야한다.

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

주석을 달아야하는 대부분의 상황이 코드품질이 나쁘기 때문이다. 이때는 주석을 달아야지! 가 아니라 코드를 정리해야지! 로 마음먹어야한다.
표현력이 풍부하고 깔끔하다면 주석은 필요없다. 주석을 달 시간에 코드품질을 올리기위해 노력해라.

좋은 주석

물론 어떤 주석은 필요하고 유익할수도 있다. 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실. (?!)

법적인 주석

회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 넣어야 하는 경우. 저작권정보와 소유권 정보 등등. (대부분 IDE 가 알아서 달아준다)

정보를 제공하는 주석

// kk:mm:ss EEE, M dd, yyyy. 
Pattern timeMatcher = Pattern. compile(...);

정규표현식과 같이 함수 이름으로 넣기 애매한 경우는 OK!

의도를 설명하는 주석

누가봐도 이상하지만 어떻게든 처리한 코드에 대해 의도를 처리해야하 때?

(이거 자체가... 개선이 필요한 코드가 아닌가? 이해가 잘...)

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

모호한 인수나 반환값. 일반적으로 인수나 반환값을 명확하게 만들면 좋겠지만, 그럴 수 없을때엔 의미를 명료하게 밝히는 주석이 유용하다.

assertTrue(a. compareTo(a) = 0); //a=a 
assertTrue(a.compareTo(b) =! 0); //a =! b 
assertTrue(ab.compareTo(ab) = 0); //ab = ab

물론 주석을 관리하기 쉽지 않으니, 더 나은 방법을 찾을 수 있도록 고민해야한다.

결과를 경고하는 주석

다른 프로그래머에게 결과를 경고하는 주석.

// 여유시간이 충분하지 않다면 실행하지 마십시오.
public void _testwithReallyBigFile()  {
	writeLinesToFile(10000000);
	...
}

TODO 주석

앞으로 해야할 일들. 개선사항이나, 수정해야 할 부분등...

(하지만 TODO는 적어두기만 하고 사라지지 않는다...)

중요성을 강조하는 주석

겉으로 보기에 별거 아닌 코드로 보여지지만 수정이나 삭제시 치명적인 문제를 야기할 수 있는 부분에 대해서는 주석이 유효하다.

나쁜 주석

대다수의 주석이 이 범주에 속한다. (...!) 주석으로 허술한 코드를 지탱하거나, 변명하거나 합리화하거나...

주절거리는 주석

마지못해서 다는 주석은 없느니만 못하다. 주석을 달기로 결정했다면 충분한 시간을 들여서 최고의 주석을 달아야한다.

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

함수명을 통해 충분히 표현된 내용을 주석으로 또 달았다. 주석이 코드보다 더 많은 정보를 제공하지 못한다면 필요 없는 주석이 된다.

// this.closed 가 true 일 때 반환되는 유틸리티 메서드다.
public synchronized void waitForClose(final long timeoutMillis)

오해할 여지가 있는 주석

의도는 좋더라도 읽는 사람의 입장에서 오해할 수 있다면 나쁜 주석. 잘못된 이해가 전파되지 않도록 명확해야한다.

(그걸 모르는건 아니지만... 다들 생각이 다르니까... 라고 변명해본다.)

의무적으로 다는 주석

모든 함수에 의무적으로 주석을 달아야 한다는건 어리석다. 이런 주석들은 코드를 복잡하게 만들고, 혼동과 무질서를 초래한다.

(아무 의미없이 라인만 차지하는 주석은 차후에 관리되지 못할 확률이 100%)

이력을 기록하는 주석

코드가 수정된 이력등을 날짜를 달고, 수정내용을 추가하여 주석으로 남기기도 하는데, 이는 소스코드 관리 시스템 (Git?) 이 없었던 시대의 편린이다. 이제는 혼란만 가중되니 완전히 제거하는편이 좋다.

있으나 마나 한 주석

너무나도 당연한 사실을 언급하는 주석. 맥락은 똑같다. 새로운 정보를 제공하지 못한다면 주석으로서의 의미는 없다. 있으나 마나 한 주석이 계속 반복되면 개발자는 주석을 읽지 않게되고, 정말로 중요한 내용조차 패스될수도 있다.

위치를 표시하는 주석

소스파일에서 어떤 묶음 (extension...? MARK...?) 의 위치에 주석을 달기도 한다. 이러한 주석 아래 특정 정보를 모아놓으면 유용한 경우도 있긴 하지만 가독성만 낮아지므로 제거하는것이 마땅하다.

닫는 괄호에 다는 주석

중첩이 심하고 장황한 함수라면 의미가 있을지 모르지만, 작고 캡슐화된 함수에서는 잡음일 뿐이다.

func a() {
} // a func!

주석으로 처리한 코드

주석으로 처리된 코드는 다른 사람들이 지우기를 주저한다. 이유가 있어 남겨놓았다고 생각하니까! 이런 코드가 쌓이고, 썩어간다. (...뜨끔)
이제는 소스 코드 관리 시스템이 유용하니 지우는것을 망설이지 말자. 잃어버릴 염려는 없다.

전역 정보

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

너무 많은 정보

주석을 메모장처럼 쓰지 말아라. 코드에 관한 내용이 아니라면 ㄱ건 불가사의한 정보일 뿐이다.

마무리

(주석을 달아야할때 한번쯤 떠올려봐야할 내용. 회사에서 문서화를 요구할때 주석을 추출하여 대신 사용하기도 했는데... 그경우 위의 룰들을 너무나도 많이 오버하게된다. 그럴땐 차라리 다른 doc 를 만드는것이 바람직할것같다...)

profile
그저 오래된 iOS 개발자.

0개의 댓글