[CleanCode] 6~7일차 - 4장 TIL

4장
주석

 

책에서 기억하고 싶은 내용

• 주석은 나쁜 코드를 보완하지 못한다
  
  • 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 훨씬 좋다.
  • 많은 경우 주석에 달려는 설명을 함수로 표현해도 충분하다.
• 좋은 주석
  • 계약 조건, 법적 정보, 표준 라이선스, 외부 문서 등의 표기
  • 기본적인 정보 제공 - 하지만 함수 표기가 더 낫다
  • 의도 설명
  • 의미 명료 - 인수나 반환값 자체를 명료하게 하는 것이 더 낫지만 못할 때
  • 결과 경고 - 더 나은 해결책이 있을 수 있겠지만, 주석이 합리적일 때도 있다.
  • 앞으로 할일 - 핑계가 되어서는 안된다.
  • 중요성 강조
• 나쁜 주석
  • 이해가 안되는 주석
  • 같은 이야기를 중복하는 주석 - 코드가 더 깔끔하다
  • 오해할만한 주석
  • 의무적인 주석
  • 이력 기록용 주석, 공로나 저자 표시, 주석처리한 옛날 코드 - 소스 코드 관리 시스템을 이용하자
  • 너무 당연한 사실을 기록한 주석
  • 닫는 괄호에 표기
  • 너무 많은 정보나 모호한 관계
• 가능한 함수나 변수로 표현하자

오늘 읽은 소감

확실히 좋은 주석의 예 보다는 나쁜 주석의 예가 많았다. 그만큼 주석 사용이 잦아서는 좋은 경우가 없다는 걸까?
좋은 주석은 확실히 기억해두고자 다 적었고, 나쁜 주석은 내가 종종 사용했던 것 같아 기록했다.
사실 난 읽기 쉬우라고 작성했다고 생각했는데 이렇게 돌이켜 보니 모호하고 애매한게 많았을 것 같다.
특히 코드로 충분히 설명가능한 걸 코드를 더럽게 쓰고 주석으로 설명했던 과거가 떠올라 조금 부끄럽다.

궁금하거나 더 공부해야할 내용

공개 API에서의 JavaDocs : 다른 개발자들이 API를 사용할 때 참고해서 쉽게 이해하고 조치할 수 있도록 하는 설명글

• 클래스/메서드 설명:
• @param:
• @return:
• @throws또는@exception :
• @see:

 

 나의 최애 북틸 리스트

https://mujilog.tistory.com/category/book/cleancode

'book/cleancode' 카테고리의 글 목록

책을 읽다가 모르는걸 찾다가 이분 티스토리를 접하게 됐다. 동일한 TIL인데 내가 헷갈리거나 잘 모르는 개념에 대해 한번씩 짚고 넘어가주셔서 잘 참고가 됐다. 그래고 현직자 입장에서의 적용법같은걸 들을 수 있어서 좋았다.

https://nomadcoders.co/community/thread/10170

[클린코드 TIL] 4장. 주석 – 노마드 코더 Nomad Coders

노마드코더 커뮤니티는 처음 들어가봤는데 꼼꼼하게 메모하시고 소감도 쏙쏙 들어와서 좋았다.

https://kirahaa.github.io/clean-code-03/

All posts

깃허브에서도 둘러봤는데 정말 딱알기좋게 깔끔하게 정리되어 있었다!