TIL (Today I Learned)

2022.02.24

오늘 읽은 범위

4장. 주석

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

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

• 코드로 의도를 표현하라!

좋은주석

• 법적인 주석

  • 회사에서 정해놓은...라이선스 등

• 정보 제공 주석

// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile(
 "\\\\d*:\\\\d*:\\\\d* \\\\w*, \\\\w* \\\\d*, \\\\d*");

• 의도를 설명하는 주석

public void testConcurrentAddWidgets() throws Exception {
 WidgetBuilder widgetBuilder =
 new WidgetBuilder(new Class[]{BoldWidget.class});
 String text = "'''bold text'''";
 ParentWidget parent =
 new BoldWidget(new MockWidgetRoot(), "'''bold text'''");
 AtomicBoolean failFlag = new AtomicBoolean();
 failFlag.set(false);
 // 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도한다.
 for (int i = 0; i < 25000; i++) {
 WidgetBuilderThread widgetBuilderThread =
 new WidgetBuilderThread(widgetBuilder, text, parent, failFlag);
 Thread thread = new Thread(widgetBuilderThread);
 thread.start();
 }
 assertEquals(false, failFlag.get());
}

• 의미를 명료하게 밝히는 주석

• 결과를 경고하는 주석

// 여유 시간이 충분하지 않다면 실행하지 마십시오.

• TODO 주석

• 중요성 강조 주석

String listItemContent = match.group(3).trim();
// 여기서 trim은 정말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));

• 공개 API에서 Javadocs

나쁜 주석

• 주절거리는 주석

• 같은 이야기를 중복하는 주석

• 오해할 여지가 있는 주석

• 의무적으로 다는 주석

• 이력을 기록하는 주석

• 있으나 마나 한 주석

• 무서운 잡음

  • 안좋은 javadocs?

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

• 위치를 표시하는 주석 (///////active//////////

• 닫는 괄호에 다는 주석

• 공로를 돌리거나 저자를 표시하는 주석

• 주석으로 처리한 코드

• HTML 주석

• 전역 정보

• 너무 많은 정보

• 모호한 관계

• 함수 헤더

• 비공개 코드에서 Javadocs

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

• 되돌아보니 안 좋은 주석을 다는 것이 습관이 되있었다. "주석을 달지 않고 코드로 표현하는 것"에 충실했지만, 달게되는 주석들은 십중팔구 책에서 예시로 드는 것과 일치했다.

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