TIL 4장 주석

오늘 TIL 3줄 요약

• 주석을 다는 것보다는 코드만 보아도 알 수 있도록 코드를 짜야한다. 
• 이름을 잘 지으면 주석을 달지 않아도 될 수 있다. 
• 주석을 잘못 달면 오히려 독이 될 수 있다. 

 

TIL (Today I Learned)

2022.04.28

 

오늘 읽은 범위

4장. 주석

 

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

• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다. 자신이 저지른 난장판을 주석으로 설명하려 애쓰는 대신에 그 난장판을 깨끗이 치우는 데 시간을 보내라! (p.69)
• 몇 초만 더 생각하면 코드로 대다수 의도를 표현할 수 있다. 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다. (p.70)

 

• 좋은 주석
• 1. 법적인 주석
• 2. 정보를 제공하는 주석
• 3. 의도를 설명하는 주석
• 4. 의미를 명료하게 밝히는 주석
• 5. 결과를 경고하는 주석
• 6. TODO 주석(앞으로 해야할 일, 다른 사람에게 해야할 일을 알리고 싶을 때.)
• 7. 공개 API에서 JavaDocs

 

• 나쁜 주석 
• 1. 주절거리는 주석(이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석이다.)
• 2. 같은 이야기를 중복하는 주석
• 3. 오해할 여지가 있는 주석, 의무적으로 다는 주석
• 4. 이력을 기록하는 주석
• 5. 있으나 마나 한 주석(너무 당연한 사실을 언급)
• 6. 무서운 잡음(잘못된 욕심)
• 7. 함수나 변수로 표현할 수 있다면 주석
• 8. 위치를 표시하는 주석
• 9. 닫는 괄호에 다는 주석(닫는 괄호에 주석을 달아야겠다는 생각이 든다면 대신에 함수를 줄이려 시도하자.)
• 10. 공로를 돌리거나 저자를 표시하는 주석
• 11. 주석으로 처리한 코드(소스 코드 관리 시스템이 우리를 대신해 코드를 기억해준다.)
• 12. HTML 주석 
• 13. 전역 정보(코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지마라.)
• 14. 너무 많은 정보
• 15. 모호한 관계
• 16. 함수 헤더(짧고 한 가지만 수행하며 이름을 잘 붙인 함수가 주석으로 헤더를 추가한 함수보다 훨씬 좋다.)
• 17. 비공개 코드에서 JavaDocs

 

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

• 지금까지 불필요한 주석을 다는데에 크게 잘못하지 않고 있다고 생각이 들었다.
• 주석을 꼭 달아야한다면 정성을 들여서 달아야겠다.