TIL (Today I Learned)

2022.01.22

오늘 읽은 범위

4장. 함수

책에서 기억하고 싶은 내용을 써보세요.

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

  표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가 복잡하고 어수선하며 주석이 많이 달린코드보다 훨씬 좋다. 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗히 치우는데 시간을 보내라

• 코드로 의도를 표현하라

• 좋은 주석

  1. 법적인 주석

  2. 정보를 제공하는 주석

  3. 의도를 설명하는 주석

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

  5. 결과를 경고하는 주석

  6. TODO(앞으로 할 일) 주석

  7. 중요성을 강조하는 주석

  8. 공개 API에서 Javadocs

• 나쁜 주석

  1. 주절거리는 주석

  2. 같은 이야기를 중복하는 주석

  3. 오해할 여지가 있는 주석

  4. 의무적으로 다는 주석

  5. 이력을 기록하는 주석

  6. 있으나 마나 한 주석 -> 함수나 변수로 표현 할 수 있다면 주석을 달지 말라

  7. 위치를 표시하는 주석

  8. 닫는 괄호에 다는 주석

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

  10. 주석으로 처리한 코드

  11. HTML 주석

  12. 전역 정보 (근처에 있는 코드만 주석으로 달 것 -> 시스템의 전반적인 정보를 기술하지 마라

  13. 너무 많은 정보

  14. 흥미로운 역사나 정보

  15. 모호한 관계 (코드를 설명하기 위해 주석이 존재하는데 주석에 설명이 필요해선 안된다.)

  16. 함수헤더 (이름을 잘 지은 함수는 주석이 필요하지 않다

      )

  17. 비공개 코드에서 Javadocs

오늘 읽은 소감은? 떠오르는 생각을 가볍게 적어보세요

• 솔직히 좋은 주석을 잘 구분하지 못한다. 나는 코드에 주석을 거의 달지 않았었고 최근부터 협업 과정에서 최소한에 주석만 달고 있다. 주로 함수 선언부에 주석을 다는 편이 었는데 이 책을 읽고 내가 의무적으로 주석을 작성할 뿐 독자를 배려해서 주석을 짜고 있지 않았다는 사실을 실감하게 되었다. 앞으로 주석을 달아야 겠다는 생각이 들때면 먼저 주석을 대체할만큼 코드를 정돈할 방법이 없을까 충분히 고민하는 시간을 갖고 독자를 배려하는 주석을 달 수 있도록 노력해야겠다