Clean Code 4. 주석

4 minute read

목차

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

  • 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
  • 나쁜 코드를 주석으로 설명하려 애쓰는 대신 깨끗한 코드로 다시 짜라.

코드로 의도를 표현하라

  • 코드로 대다수의 의도를 표현 할 수 있다.
  • 주석으로 달려는 설명을 함수로 만들어 표현하라.
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))

if (employee.isEligibleForFullBenefits())

좋은 주석

  • 법적인 주석
    • 각 소스 파일 첫 머리에 주석으로 들어가는 저작권 정보와 소유권 정보
  • 정보를 제공하는 주석
    • 기본적인 정보를 주석으로 제공하면 편리하다.
    • 함수 이름을 다시 짓거나 클래스를 만들면 더 좋다.
// kk:mm:ss EEE, MMM dd, yyyy 형식이다.
Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");
  • 의도를 설명하는 주석
    • 코드만으로 의도를 설명하기 어려울 때가 있다.
ArrivalRecordChanged?.Invoke(this, e);
gcGridControl.RefreshData(); // Arrival Record 변경시 다음 행이 제대로 그려지지 않으므로 반드시 Refresh 를 한번 해야 한다.
  • 의도를 명료하게 밝히는 주석
    • 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
    • 주석이 올바른지 검증할 수 없어서 위험할 수 있으므로 정확히 달도록 각별히 주의해야 한다.
public void testCompareTo() throws Exception
{
  WikiPagePath a = PathParser.parse("PageA");
  WikiPagePath ab = PathParser.parse("PageA.PageB");
  WikiPagePath b = PathParser.parse("PageB");
  WikiPagePath aa = PathParser.parse("PageA.PageA");
  WikiPagePath bb = PathParser.parse("PageB.PageB");
  WikiPagePath ba = PathParser.parse("PageB.PageA");
  
  assertTrue(a.compareTo(a) == 0);     // a == a
  assertTrue(a.compareTo(b) == 0);     // a != b
  assertTrue(ab.compareTo(ab) == 0);   // ab == ab
  assertTrue(a.compareTo(b) == -1);    // a < b
  assertTrue(aa.acompareTo(ab) == -1); // aa < ab
  assertTrue(ba.compareTo(bb) == -1);  // ba < bb
  assertTrue(b.compareTo(a) == 1);     // b > a
  assertTrue(ab.compareTo(aa) == 1);   // ab > aa
  assertTrue(bb.compareTo(ba) == 1);   // bb > ba
}
  • 결과를 경고하는 주석
    • 주석때문에 실수를 면할 수 있다.
public static SimpleDateFormat makeStandardHttpDateFormat()
{
  // SimpleDateFormat은 스레드에 안전하지 못하다.
  // 따라서 각 인스턴스를 독립적으로 생성해야 한다.
  SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
  df.setTimeZone(TimeZone.getTimeZone("GMT"));
  regurn df;
}
  • TODO 주석
    • 필요하지만 당장 구현하기 어려운 업무나 기술에 주석을 남겨두면 편하다.
    • TODO로 떡칠한 코드는 바람직하지 않다.
  • 중요성을 강조하는 주석
String listItemContent = match.group(3).trim();
// 여기서 trim은 절말 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 동백이 있으면 다른 문자열로 인식되기 때문이다.
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.emd()));
  • 공개 API에서 Javadocs
    • 설명이 잘된 공개 API는 유용하다.

나쁜 주석

  • 대다수 주석은 나쁜 주석이다.
  • 주절거리는 주석
    • 특별한 이유없이 주석을 단다면 시간 낭비다.
public void loadProperties()
{
  try {
    String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
    FileInputStream propertiesStream = new FileInputStream(propertiesPath);
    loadedProperties.load(propertiesStream);
  }
  catch(IOException e) {
    // 속성 파일이 없다면 기본값을 모두 메모리로 읽어 들였다는 의미다.
  }
}
  • 같은 이야기를 중복하는 주석
    • 간단한 함수의 헤더 주석은 같은 코드 내용을 중복한다.
    • 자칫 코드보다 주석을 읽는 시간이 더 길어진다.
// this.closed가 true일 때 반환되는 유틸리티 메서드다.
// 타임아웃에 도달하면 예외를 던진다.
public synchronized void waitForClose(final long timeoutMillis) throws Exception 
{
  if (!closed) {
    wait(timeoutMillis);
    if (!closed) {
      throw new Exception("MockResponseSender could not be closed");
    }
  }
}
  • 오해할 여지가 있는 주석
    • 주석에 담긴 잘못된 정보로 인해 함수를 호출한 프로그래머가 골머리를 앓을 수 있다.
  • 의무적으로 다는 주석
    • 의무적으로 주석을 다는 규칙을 정하면 안된다.
    • 코드를 복잡하게 만들며 혼동과 무질서를 초래한다.
  • 이력을 기록하는 주석
    • git이 없었을 때 모든 모듈 첫머리에 변경 이력을 기록하는 관례가 있었다.
    • git을 이용하면 되므로 완전 제거해야 한다.
  • 있으나 마나 한 주석
    • 너무 당연한 사실을 언급하면서 새로운 정보를 제공하지 못하는 주석은 바람직하지 않다.
    • 개발자가 코드를 읽으며 자동으로 주석을 보지 않게 되고, 코드가 바뀌면서 주석은 거짓말이 된다.
    • 있으나 마나 한 주석을 달려는 유혹에서 벗어나 코드를 정리하면 더 행복한 프로그래머가 된다.
// 월 중 일자를 반환한다.
public int getDayofMonth()
{
  return dayOfMonth;
}
  • 무서운 잡음
    • 때로는 Javadocs도 잡음이다.
    • 목적이 없는 주석 양산은 복붙 오류를 야기한다.
// The name
private String name;

// The version
private String version;

// The licenceName
private String licenceName;

// The version
private String info;
  • 함수나 변수로 표현할 수 있다면 주석은 달지 마라.
// 젼역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubSystems().contains(subSysMod.getSubSystem())) ...

ArrayList moduleDependees = smodule.getDependSubSystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) ...
  • 위치를 표시하는 주석
    • 특정 기능을 모으려는 의도이지만 가독성만 낮추고 관리가 힘들다.
//////////////////////// Action ///////////////////////
  • 닫는 괄호에 다는 주석
    • 작고 캡슐화된 함수에는 잡음일 뿐이다.
    • 닫는 괄호에 주석을 달아야겠다는 생각이 든다면 함수를 줄이려 시도해야 한다.
  • 공로를 돌리거나 저자를 표시하는 주석
    • 오랫동안 코드에 방치되어 점차 부정확하고 쓸모없는 정보로 변하기 쉽다.
    • git을 이용하면 되므로 완전 제거해야 한다.
  • 주석으로 처리된 코드
    • 다른 사람들이 이유가 있어 남겨놓았으리라고, 중요하니까 지우면 안된다고 생각하여 지우기를 주저하게 된다.
    • git을 이용하면 되므로 완전 제거해야 한다.
  • HTML 주석
    • 읽기가 힘들고 관리하기 어렵다.
  • 전역 정보
    • 코드 일부에 주석을 달면서 시스템의 전반적인 정보를 기술하지 마라.
    • 함께 고쳐지지 않기 때문에 관리하기 힘들다.
// 적합성 테스트가 동작하는 포트: 기본값은 8082
public void setFitnessePort(int fitnessePort)
{
  this.fitnessePort = fitnessesPort;
}
  • 너무 많은 정보
    • 흥미로운 역사나 관련없는 정보를 장황하게 늘어놓지 마라.
  • 모호한 관계
    • 주석과 주석이 설명하는 코드는 둘 사이의 관계가 명백해야 한다.
    • 주석 자체가 다시 설명을 요구하면 안된다.
  • 함수 헤더
    • 헤더에 설명이 달린 함수보다 짧고 한가지만 수행하며 이름을 잘 붙인 함수가 더 좋다.
  • 비공개 코드에서 Javadocs
    • 시스템 내부에 속한 클래스와 함수에 Javadocs를 생성할 필요는 없다.

과제

Leave a comment

You may also enjoy