Clean Code 4 장 주석

2012 02. 03원종필

주석 (Comment)

코드로 의도를 표현하지 못해 ,실패를 만회하기 위해서 사용한다 .

주석을 유지하고 보수하기란현실적으로 불가능하다

부정확한 주석은 아예 없는 주석보다 훨씬 더 나쁘다

진실은 한곳에만 존재한다 ! 바로 코드 (code).

주석을 엄격하게 관리하는 방향 보다는코드를 깔끔하게 정리하여 주석이 필요없는 방향으로 힘을 쏟아라

주석을 달아야 겠다 ??

코드를 정리해야 한다

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

코드로 의도를 표현하라 !!

좋은 주석 ( 글자값을 하는 주석 )

법적인 주석

정보를 제공하는 주석

의도를 설명하는 주석 ( 결정에 깔린 의도를 설명한다 )

좋은 주석 ( 글자값을 하는 주석 )

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

결과를 경고하는 주석

TODO 주석 ( 나쁜 코드를 남기는 핑계가 되어서는 안된다 )

공개 API 에서 JavaDocs

나쁜 주석

허술한 코드를 지탱하거나엉성한 코드를 변명하거나미숙한 결정을 합리화하는 등프로그래머가 주절거리는 독백에해당하는 대부분의 주석들 !!

주석을 달기로 결정했는가 ?

충분한 시간을 들여 최고의주석을 달도록 노력해야 한다

의무감 / 프로세스에 의해 마지못해 주석을 달다면 시간낭비일 뿐이다 !!

나쁜 주석

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

주석이 같은 코드의 내용을 그대로 중복한다코드보다 주석을 읽는 시간이 더 오래 걸린다

나쁜 주석

이력을 기록하는 주석

과거에는 필요했을지 모르지만이제는 코드 관리 시스템으로 관리할 수 있다

나쁜 주석

있으나 마나한 주석

주석이 지나친 참견이라 주석을 무시하게 된다코드를 읽으면서 자동을 주석을 건너뛴다코드가 바뀌면서 주석은 거짓말로 변한다 .

나쁜 주석

닫는 괄호에 다는 주석

의미가 있을 수도 있지만 , 작고 캡슐화된함수에는 잡음일 뿐이다 .닫는 괄호에 주석을 달아야 겠다면함수를 줄이려고 시도해 봐라 .

나쁜 주석

주석으로 처리된 코드는 다른사람이 지우기를 주저한다이유가 있어 남겨놓았을 것이다 . 중요하니까 지우면 안된다 생각한다 !!그래서 쓸모 없는 코드가 점차 쌓여간다 .코드 관리 시스템을 통해서 모두 관리 가능하다그냥 삭제해라 . 잃어버릴 염려는 없다 !

주석으로 처리한 코드들 / 저자를 표시하는 주석

나쁜 주석

HTML 주석 , 너무나 많은 정보를 담는 주석 ,주석과 코드의 설명이 명백하지 않은 모호한 주석 ,짧은 함수에 긴 설명 주석 ,비공개코드의 JAvaDocs........

Q/A

END