[클린코드] TIL (4장. 주석)

오늘 TIL 3줄 요약

• 주석은 필요악이다
• 주석 대신 코드로 의도를 표현하라
• 주석은 반드시 필요할 때만, 최소한으로 사용하라

책에서 기억하고 싶은 내용

• 주석은 '필요악' 이다. 우리에게 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 전혀 필요하지 않으리라. 하지만 그렇지 못해서 쓰는 것이 주석 (그만큼 주석은 안쓰는 것이 좋다.)
• 주석은 나쁜 코드를 보완하지 못한다. 나쁜 코드를 주석으로 설명하려 애쓰는 대신 코드를 수정하라.
• 코드로 의도를 표현하라

 

<좋은 주석>

- 법적인 주석

-정보를 제공하는 주석

-의도를 설명하는 주석

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

-결과를 경고하는 주석

-TODO주석

-중요성을 강조하는 주석

 

<나쁜 주석>

-주절거리는 주석

-같은 이야기를 하는 주석

-오해할 여지가 있는 주석

-의무적으로 다는 주석

-있으나 마나 한 주석

-무서운 잡음 (ex.문서를 제공해야 한다는 잘못된 욕심으로 탄생한 주석)

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

-위치를 표시하는 주석(너무 자주 사용하지 않는다면 반드시 필요할 때만, 아주 드물게 사용하는 편이 좋음)

-닫는 괄호에 다는 주석

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

-주석으로 처리한 코드

-HTML코드

-전역정보(근처에 있는 코드만 기술하라)

-너무 많은 정보

-모호한 관계(주석과 코드의 관계를 명백히 하여 읽는 사람이 주석을 읽고 무슨 소린지 알게 해야함)

-함수 헤더

-비공개 코드에서 Javadocs

 

오늘 읽은 소감은?

나는 아직 코드 읽기가 익숙하지 않아서 그런지 주석이 있는 코드가 편하다고 생각했는데, 주석은 필요악이라고 하니 조금 찔린다. 특히 위치를 표시하는 주석은 정말 필요하다고 생각했는데 이것마저도 안쓰는게 좋다니..ㅎㅎ 주석보다는 코드를 더 읽기 좋게 쓰자!!!