TIL (Today I Learned) 날짜

2022. 04. 29

오늘 읽은 범위

4장. 주석

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

• 잘 달린 주석은 그 어떤 정보보다 유용하다. 경솔하고 근거 없는 주석은 코드를 이해하기 어렵게 만든다. 오래되고 조잡한 주석은 거짓과 잘못된 정보를 퍼뜨려 해악을 미친다.

• 진실은 한곳에만 존재한다. 바로 코드다. 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는(간혹 필요할지라도) 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

• 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드가, 복잡하고 어수선하며 주석이 많이 달린 코드보다 훨씬 좋다.

• 몇 초만 더 생각하면 코드로 대다수 의도를 표현할 수 있다. 많은 경우 주석으로 달려는 설명을 함수로 만들어 표현해도 충분하다.

• 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이라는 사실을!

• 좋은 주석: 법적인 주석 / 정보를 제공하는 주석 / 의도를 설명하는 주석 / 의미를 명료하게 밝히는 주석 / 결과를 경고하는 주석 / TODO 주석 / 중요성을 강조하는 주석 / 공개 API에서 Javadocs

• 나쁜 주석: 주절거리는 주석 / 같은 이야기를 중복하는 주석 / 오해할 여지가 있는 주석 / 의무적으로 다는 주석 / 이력을 기록하는 주석 / 있으나 마나 한 주석 / 무서운 잡음 / 함수나 변수로 표현할 수 있다면 주석을 달지 마라 / 위치를 표시하는 주석 / 닫는 괄호에 다는 주석 / 공로를 돌리거나 저자를 표시하는 주석 / 주석으로 처리한 코드 / HTML 주석 / 전역 정보 / 너무 많은 정보 / 모호한 관계 / 함수 헤더 / 비공개 코드에서 Javadocs

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

• 이번 챕터에서 이야기한 나쁜 주석에 해당하는 대다수가 지금껏 내가 코딩을 하면서 주석을 달았던 것들이라 많은 반성을 하게된다.

• 주절거리는 주석을 작성할 시간에 변수명, 함수명을 어떻게 더 표현력 있게 만들지? 리펙토링을 더 할지? 더 간결한 로직은 없는지? 고민 하고 수정하며 코드에 신경써야 겠다는 다짐을 해본다.

• '진실은 한곳에만 존재한다. 바로 코드다' 이 말을 항상 다짐하며 개발을 해 나가야 겠다.