[클린코드]4.주석

예전에 《클린코드》를 읽고 나서 운영하는 시스템의 코드를 유지보수할 때마다 많은 주석을 삭제했다. 실제로 유지보수하면서 주석이 크게 도움되지 않았기 때문이다.

나 또한 다른 사람이 코드를 제대로 이해하지 못할까봐 주석을 달아놓고는 했었다. 그런데 이제는 그런 걱정이 든다면 코드를 다시 짠다. 코드만으로 이해할 수 있도록.

📆TIL(Today I Learned) 날짜

2022.03.26

📑오늘 읽은 범위

4.주석

✍🏻책에서 기억하고 싶은 내용

프로그래밍 언어 자체가 표현력이 풍부하다면, 아니 우리에게 프로그래밍 언어를 치밀하게 사용해 의도를 표현할 능력이 있다면, 주석은 거의 필요하지 않으리라. 아니, 전혀 필요하지 않으리라.

주석은 언제나 실패를 의미한다. (…) 그러므로 주석이 필요한 상황에 처하면 곰곰이 생각하기 바란다. 상황을 역전해 코드로 의도를 표현할 방법은 없을까?

내가 이렇듯 주석을 무시하는 이유가 무엇이냐고? 거짓말을 하니까. 항상도 아니고 고의도 아니지만 너무 자주 거짓말을 하니까. 주석은 오래될수록 코드에서 멀어진다. 오래될수록 완전히 그릇될 가능성도 커진다. 이유는 단순하다. 프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하니까.

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

좋은 주석
👉🏻 법적인 주석
👉🏻 정보를 제공하는 주석
👉🏻 의도를 설명하는 주석
👉🏻 의미를 명료하게 밝히는 주석
👉🏻 결과를 경고하는 주석
👉🏻 TODO 주석
👉🏻 중요성을 강조하는 주석
👉🏻 공개 API에서 Javadocs

나쁜 주석
👉🏻 주절거리는 주석 : 주석을 달기로 했다면 충분한 시간을 들여 최고의 주석을 달도록 노력한다.
👉🏻 같은 이야기를 중복하는 주석
👉🏻 오해할 여지가 있는 주석
👉🏻 의무적으로 다는 주석
👉🏻 이력을 기록하는 주석 : 당시에는 소스 코드 관리 시스템이 없었으니까. 하지만 이제는 혼란만 가중할 뿐이다. 완전히 제거하는 편이 좋다.
👉🏻 있으나 마나 한 주석 : 너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석
👉🏻 무서운 잡음
👉🏻 함수나 변수로 표현할 수 있다면 주석을 달지 마라
👉🏻 위치를 표시하는 주석
👉🏻 닫는 괄호에 다는 주석 : 중첩이 심하고 장황한 함수라면 의미가 있을지도 모르지만 (우리가 선호하는) 작고 캡슐화된 함수에는 잡음일 뿐이다. 그러므로 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자.
👉🏻 공로를 돌리거나 저자를 표시하는 주석
👉🏻 주석으로 처리한 코드
👉🏻 HTML 주석
👉🏻 전역정보
👉🏻 너무 많은 정보
👉🏻 모호한 관계
👉🏻 함수 헤더
👉🏻 비공개 코드에서 Javadocs

❓궁금한 내용, 잘 이해되지 않는 내용

• 없음