[TIL] 클린코드 : 4장. 주석

오늘 TIL 3줄 요약

• 확실하게 코드로 의도표현을 하자

• 게으른 나쁜 주석은 지양하자

• 코드만이 진실되게 말한다.

TIL (Today I Learned)

2024.06.27

오늘 읽은 범위

• 4징 주석

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

• 나라면 코드를 깔끔하게 정리하고 표현력을 강화하는 방향으로, 그래서 애초에 주석이 필요 없는 방향으로 에너지를 쏟겠다.

• 코드만이 자기가 하는 일을 진실되게 말한다. 코드만이 정확한 정보를 제공하는 유일한 출처다. (p.69)

• 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.

• 좋은 주석 : 주석을 달지 않을 방법을 찾아낸 주석

  • 법적인 주석 : 저작권 정보와 소유권 정보, 표준 라이선스나 외부 문서 참조 가능

  • 정보를 제공하는 주석 : 기본적인 정보를 주석으로 제공

  • 의도를 설명하는 주석 : 주석은 구현을 이해하게 도와주는 선을 넘어 결정에 깔린 의도까지 설명하기도 한다.

  • 의미를 명료하게 밝히는 주석 : 모호한 인수나 반환값 의미를 읽기 좋게 표현하면 이해가 쉬어워진다. 표준 라이브러리나 병경하지 못하는 코드에 속할 때 유용하다.

  • 결과를 경고하는 주석

  • TODO 주석 : 당장 구현하기 어려운 업무 기술, 알람 및 수정요청, 문제확인 요청들에 유용

  • 중요성을 강조하는 주석

• 나쁜 주석 : 대다수 주석이 속한다.

  • 주절거리는 주석 : 주석을 이해하기위해 코드를 보게해서는 안된다.

  • 같은 이야기를 중복하는 주석 : 코드 읽는 것보다 주석 읽는 시간이 더 오래걸릴 수도 있다.

  • 오해할 여지가 있는 주석

  • 의무적으로 다는 주석 : 필수적인 JavaDocs, JSDocs 작성 규칙일 경우

  • 이력을 기록하는 주석 / 공로를 돌리거나 저자를 표시하는 주석 : 소스 코드 관리 시스템을 쓰자

  • 함수나 변수로 표현할 수 있다면 주석을 달지 마라

  • 위치를 표시하는 주석

  • 모호한 관계 : 주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.

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

• 프로젝트시에는 주석을 잘 쓰지않아서 공감가는 것은 없었다.

• 저자는 주석을 남발 하는 것은 실력의 문제로 판단하는 것으로 보인다. 다시 생각해보면 주석이라는 지름길을 사용하기위해 함수 구현시 고민을 깊게하지 않는 다는 것을 싫어하는 게 아닐까.

• 주석으로 이력관리 한다고는 들은적이 있는데 정말 책에서 주석을 보게되니 신기했다.

궁금한 내용이 있거나, 잘 이해되지 않는 내용이 있다면 적어보세요.

• 아 자바코드 힘들어

나의 최애 북틸

• seunghyun2 : 챌린지를 다시 이어나가게 해주셨습니다. 감사합니다. 하핫

• Sohyun Lim : 반가운 이름에 클릭했더니 정성스러운 정리에 놀랐다.

• wltjs8958 : 다들, 이분이 성실하게 올리셨다하셔서 나도 구경갔다.