[Clean Code] 4-1 주석

주석

우리는 주석을 코드로 의도를 표현 하지 못하여 사용 한다.
그러나 과거의 주석이 미래에 실패를 불러 올 수 있다.
코드는 언제나 변화하고 진화하며 이곳 저곳 옮겨지기도 한다.
주석은 그 코드를 따라가지 못한다.

누군가는 주석을 엄격하게 관리해야 한다고 할 수도 있지만
애초에 주석이 필요하지 않도록 코드를 작성 하는데 에너지를 쏟자.

코드로 주석을 대체하라

변경 전

# 직원에게 복지 혜택을 받을 자격이 있는지 체크
if (employee.flags and HOURLY_FLAG) and employee.age > 65 :
    do_something()

변경 후

if employee.isEnoughForFullBenefits() :
    do_something()

#

이상적인 주석

public static SimpleDateFormat makeStandardHttpDateFormat()
{
    // SimpleDateFormat은 쓰레드에 안전하지 못하므로
    // 각 인스턴스는 독립적으로 생성해서 사용 필요
    SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
    df.setTimeZone(TimeZone.getTimeZone("GMT"));
    return df;
}

TODO 로 당장 구현할 필요 없거나, 필요 없어 지거나, 문제가 있는 부분 등에 대해서 유용하게 사용 할 수 있다.

def do_something():
    # TODO: something 을 해주십쇼
    pass