클린코드: 4장 주석

TIL

• 나쁜 코드에 주석을 달지마라. 차라리 코드를 고쳐라!

• 주석은 기껏해야 필요악이다. 코드를 잘 짜면 주석은 거의 필요 없다.

• 진실은 한 곳에만 존재한다. 바로 코드다.

일자

2024.02.01

오늘 읽은 범위

4장 주석

책에서 기억하고 싶은 내용

나쁜 코드에 주석을 달지 마라. 새로 짜라 68

잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다. 68

주석은 기껏해야 필요악이다. 코드를 잘 짜면 주석은 거의 필요 없다.

진실은 한 곳에만 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 한다. 69

좋은 주석

• 법적인 주석: 저작권 정보 및 소유권 정보 등

• 정보를 제공하는 주석

• 의도를 설명하는 주석

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

• 결과를 경고하는 주석

• Todo 주석

• 중요성을 강조하는 주석

나쁜 주석

• 대부분의 주석

• 주절거리는 주석: 뭔소린지 이해 안가는 주석

• 같은 이야기를 중복하는 주석: 코드 내용과 주석이 중복됨

• 오해할 여지가 있는 주석

• 의무적으로 다는 주석

• 이력을 기록하는 주석 : 요즘은 git이 다 해줌 필요없음

• 있으나 마나 한 주석

• 무서운 잡음

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

• 위치를 표시하는 주석

• 닫는 괄호에 다는 주석: 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 함수를 줄이고 깔끔하게 바꾸자

• 주석으로 처리한 코드: 어차피 이것도 git이 해줌. 그냥 지워버려도 됨

• 전역 정보: 주석 근처에 있는 코드에 대한 내용만 작성해. 시스템 전반 내용은 달지마.

• 너무 많은 정보

• 모호한 관계

• 함수 헤더: 짧은 함수는 긴 설명이 필요 없다. 짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.

오늘의 소감

주석이 나쁜지 몰랐다. 오히려 주석을 권장해왔는데. 주석을 줄이라는 내용을 보고 거의 전반적인 충격을 받았다. 앞으로 코드를 작성하는 스타일이 많이 바뀔 것 같다.

궁금하거나 잘 이해되지 않는 내용

오늘 읽은 다른사람의 TIL

https://nomadcoders.co/community/thread/9221
https://nomadcoders.co/community/thread/9223
https://nomadcoders.co/community/thread/9224
깔끔하고 가독성이 좋음!