TIL #05 주석

오늘 TIL 3줄 요약

• 주석은 나쁜 코드를 만회하기 위한 변명이다.
• 좋은 주석은 글자값을 한다. 그래도 주석을 달지 않을 방법을 찾아라.
• 대다수의 주석은 나쁜 주석이다. 주석을 줄이도록 꾸준히 노력해라.

---

TIL (Today I Learned) 날짜

• 2022. 04. 28 ~ 2022. 04. 29

오늘 읽은 범위

• 4장 주석

---

책에서 기억하고 싶은 내용들

나쁜 코드에 주석을 달지 마라. 새로 짜라.

우리는 코드로 의도를 표현하지 못해, 실패를 만회하기 위해 주석을 사용한다.

프로그래머들이 주석을 유지하고 보수하기란 현실적으로 불가능하다. 그래서 주석은 오래될수록 코드에서 멀어지고 그릇될 가능성도 커진다.

코드만이 정확한 정보를 제공하는 유일한 출처다. 그러므로 우리는 주석을 가능한 줄이도록 꾸준히 노력해야 한다.

좋은 주석

글자값을 하는 주석들. 그러나 정말로 좋은 주석은, 주석을 달지 않을 방법을 찾아낸 주석이다.

• 법적인 주석: 소스 파일 첫머리에 들어가는 저작권 정보 등. 가능하다면 표준 라이선스나 외부 문서를 참조하자.
• 정보를 제공하는 주석: 추상 메서드의 반환값 설명 등. 이것도 함수 이름에 정보를 담는 등 주석을 없앨 방법이 있다.
• 의도를 설명하는 주석: 구현의 이해를 넘어 결정에 깔린 의도를 설명함.
• 의미를 명료하게 밝히는 주석: 인수나 반환값이 변경하지 못하는 코드에 속할 때 의미를 명료하게 밝히기 위한 주석.
• 결과를 경고하는 주석: 다른 프로그래머에게 결과를 경고할 목적으로 사용
• TODO 주석: 앞으로 할 일. 주기적으로 TODO 주석을 점검해 없앨 수 있는 것은 없애야 한다.
• 중요성을 강조하는 주석: 자칫 대수롭지 않다고 여겨질 무언가를 강조하기 위해.
• 공개 API에서 Javadocs: 프로그램을 짤 때 유용하다. 그러나 이것 역시 그릇된 정보를 전달할 가능성이 있다.

나쁜 주석

대다수의 주석이 나쁜 주석이다.

허술한 코드를 지탱하거나, 엉성한 코드를 변명하거나, 미숙한 결정을 합리화하는 등 프로그래머가 주절거리는 독백에서 크게 벗어나지 못한다.

• 주절거리는 주석: 특별한 이유없이 마지못해 달아 놓은 주석. 그냥 주절거려 놓았기에 판독 불가. 바이트 낭비다.
• 같은 이야기를 중복하는 주석: 코드의 내용과 중복되는 주석. 코드보다 주석 읽는 시간이 더 오래 걸리 수도 있다.
• 오해할 여지가 있는 주석: 의도는 좋으나 엄밀하게 달지 못한 주석. 오해를 일으켜 문제 원인을 찾는데 골머리 앓게 할 수 있다.
• 의무적으로 다는 주석: 코드를 복잡하게 만들고, 혼동과 무질서를 초래한다.
• 이력을 기록하는 주석: 편집할 때마다 첫머리에 다는 주석. 소스 코드 관리 시스템을 쓰고 주석은 완전히 제거해라.
• 있으나 마나 한 주석: 너무나 당연한 내용, 아무 의미 없는 내용의 주석.
• 함수나 변수로 표현할 수 있는 주석
• 위치를 표시하는 주석: 소스 파일의 특정 위치를 표시하려는 주석. 가독성만 낮추고 독자가 흔한 잡음으로 여겨 무시하게 만든다.
• 닫는 괄호에 다는 주석: 중첩이 심하고 장황한 함수일 때 다는 주석. 대신에 함수를 줄이려는 시도를 해라.
• 주석으로 처리한 코드: 다른 사람들이 지우기를 주저하게 만들고 쓸모없는 코드가 쌓이게 만든다. 소스 코드 관리 시스템을 써라.
• HTML 주석: 혐오 그 자체. 웹페이지에 올릴 작정이라면 주석을 뽑는 도구에게 맡겨라.
• 전역 정보: 주석을 달아야 한다면 근처에 있는 코드만 기술해라.
• 모호한 관계: 주석과 주석이 설명하는 코드는 둘 사이에 관계가 명확해야 한다.
• 비공개 코드에서 Javadocs: 공개하지 않을 코드에 Javadocs는 코드만 산만해지고 쓸모 없다.

---

오늘 읽은 소감은?

• 나도 주석을 여기 저기에 많이 달았던 경험이 많다. 내가 나중에 다시 찾아볼 때 참고하기 위해, 남이 볼 때 이해할 수 있도록 곳곳에 주절 주절 많이 달았다. 당연히 주석이 도움이 될 것이라는 생각으로 달았지만, 책을 읽고 난 후 그 주석들이 정말 글자값을 했는가 다시 생각하게 만들었다. 저자의 말대로, 나의 부족한 코드를 변명하고자 주석으로 장황하게 떠들었던 것이 아닌가 반성하게 된다.

---

궁금한 내용

• Javadocs
• 소스 관리 시스템

---