Clean Code 제 4장. 주석

오늘 읽은 범위 : 4장. 주석

---

책에서 기억하고 싶은 내용

코드만이 자기가 하는일을 진실되게 말한다.

 

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

표현력이 풍부하고 깔끔하며 주석이 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다. 코드로 저지른 난장판을 주석으로 수습하려는건 깨끗한 코드를 위한 좋은 습관이 아니다.

주석은 코드에 저지른 실패를 만회하기위한 수단이 아니다.

 

대표적인 나쁜 주석

항목들을 읽으면 왜 나쁜 주석이라 말하는지 이해할 수 있을것 같다.

• 혼잣말을 주절거리는 주석
• 같은 이야기를 반복하는 주석
• 오해의 여지가 있는 애매한 내용을 담은 주석
• 의무적으로 다는 불필요한 주석
• 히스토리를 기록하는 주석
• 좋은 이름을 쓰지 않은 코드를 설명하는 주석
• 닫는 괄호에 다는 주석 (발전된 IDE와 플러그인을 이용하자)
• 위치를 표시하는 주석
• 주석으로 처리한 코드
• HTML주석
• 전역정보
• TMI 주석
• 헤더 주석

 

글자값을 하는 주석

• 첫머리의 저작권 정보와 소유권정보
• 추상메서드가 반환할 값을 설명
  (그래도 가능하다면 함수이름에 정보를 담는편이 더 좋다)
• 결과를 경고하는 주석
  (쓰레드에 불안전하거나 시간이 많이 소요되는 테스트케이스를 실행할때 주의 하는 문구 등)
• ToDo
  IDE의 발전으로 ToDo는 여러가지 방법을 통해 점검이 가능해졌다.

그럼에도 주석은 존재 자체가 위험하다. 의미를 명료하게 밝혀주는 주석내용이라고 하더라도 그 주석이 사실을 말하는지 검증하는데 들어가는 공수가 더 크다!

 

 오늘 읽은 소감

• 깃헙에 들어가서 내 코드들을 살펴보았다. 너무나도 많은 나쁜 주석들.. 리팩토링할것이 산더미인것같다. 오히려 좋아
• 이미 슬랙에서도 여러번 언급이 되었지만 Swagger와 같은 OAS(OpenApiSpecification) 가 주석의 일을 대신 혹은 더 해준다고 생각된다. 실패한 코드를 만회하는 수단이라기 보단 코드를 이해하는데 한가지의 방안을 더 제안해주는 느낌?
• 오늘은 너무나도 당연한 얘기들이다보니 술술 읽혔다. 당연한 얘기들인데도 실천을 안하고있었지만, 이렇게 되돌아 보는 기회를 가지는것도 책을 읽었기 때문에 하지 않았을까?