[til] 4장. 주석

TIL (Today I Learned) 날짜

2024년 2월 1일

오늘 읽은 범위

4장. 주석

책에서 기억하고 싶은 내용

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

2. 코드를 의도로 표현하라

3. 좋은 주석이란?

정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이지만 다음의 내용또한 좋은 주석이라고 볼 수 있다.

• 법적인 주석 : 저작권 정보나 소유권 정보 등
• 정보를 제공하는 주석
• 의도를 설명하는 주석
• 의미를 명료하게 밝히는 주석
• TODO 주석
• 죽요성을 강조하는 주석
• 공개 API에서 Javadocs : 표준 자바 라이브러리에서 사용한 Javadocs가 좋은 예이다.

  4. 나쁜 주석이란?

• 주절거리는 주석
• 같은 이야기를 중복하는 주석
• 오해할 여지가 있는 주석
• 의무적으로 다는 주석 : 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 혼동과 무질서를 초래한다.
• 이력을 기록하는 주석 : 예전에는 모듈 첫머리 주석이 바람직했지만 이제는 아니다.
• 있으나 마나 한 주석 : 너무 당연한 사실은 언급하며 새로운 정보를 제공하지 못하는 주석
• 함수나 변수로 표현할 수 있다면 주석을 달지 마라
• 위치를 표시하는 주석
• 닫는 괄호에 다는 주석 : 작고 캡슐화된 함수에는 그저 잡음일 뿐이다. 대신에 함수를 줄이려 시도하자.
• 공로를 돌리거나 저자를 표시하는 주석
• 주석으로 처리한 코드

오늘 읽은 소감

코드를 잘 작성하는 것에는 주석도 포함된다는 것을 미처 생각하지 못했었는데 이번 챕터를 읽고 새롭게 깨달았다.

다만, 프론트엔드를 공부하는 입장에서 HTML의 주석은 혐오 그 자체라는 말에 대한 나의 생각은 조금 달랐다.

HTML또한 개발자가 사용하고 읽으며 소통해야 하는 언어라고 생각한다. 또한, 사용자에게 직접 노출되는 부분이기도 하다. 이러한 관점에서 보면 HTML 코드 내의 주석도 코드의 가독성과 이해도를 높이는 데 기여할 수 있다고 생각한다.

오늘 읽은 다른사람의 TIL

• appaaaa님의 TIL 책의 페이지까지 기록한 것이 섬세하게 느껴졌다.
• topcircle님의 TIL 전반적인 내용을 상세하게 작성한 좋은 글이라고 생각되었다.
• mahnduck님의 TIL 간략하고 깔끔하게 잘 작성한 것 같다.