[클린코드] 주석 Comment

Q) 주석은 많이 있을수록 좋은가?

A) 아니오!

 

 

주석은 오래될수록 코드에서 멀어진다.

코드(Code)는 유지보수를 해도,

주석(Comment)도 함께 유지보수되기 어렵다.

 

 

주석 없이 코드만으로도

충분히 의미를 전달할 수 있다.

// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((emplotee.flags & HOURLY_FLAG) && (employee.age > 65)

 

if 조건이 길고 어렵기 때문에

주석을 달아놓은 것이지만

사실 의미 있는 이름만으로도 충분하다.

if (employee.isEligibleForFullBenefits())

 

 

📌 [클린코드] 의미 있는 이름

[클린코드] 의미 있는 이름

---

📌 좋은 주석

• 법적인 주석

• 의도 설명

• 경고

• TODO 주석

• 중요성 강조

• 정보 제공

 

 

(Good) 법적인 주석

각 소스 파일 첫머리에 들어가는 저작권 정보와 소유권 정보 등

// Copyright (C) 2022 by hyun, Inc. All right reserved.
// General Public License

 

 

(Good) 의도를 좀 더 명확하게 밝히는 주석

STL과 같이 직접 수정하기 어려울 때

모호한 인자나 반환값 의미를 명료하게 해주면 좋다.

// 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려 시도한다.
vector<thread> threadList;
for (int i = 0; i > 2500; i++) {
    threadList.push_back(thread(WidgetBuilderThread, widgetBuilder, text));
}

for (auto& widgetBuilderThread : threadList) {
    widgetBuilderThread.join();
}

 

 

(Good) 경고하는 주석

실행 결과를 미리 경고해 놓아 업무효율성 up

// 평균 10분 정도 걸리는 작업
public void getBalance() {...}

// 여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile() {...}

 

 

(Good) TODO 주석 

형상 관리시스템에 남아 있긴 하겠지만

작성자 표시도 같이 한다면 검색하기 용이하다.

// TODO(hyun)
// 1. 로깅 기능 추가 필요할 수 있음
// 2. 000 모델 도입시 함수 불필요
VOID makeVersion() {...}

 

 

 

(Good) 중요성 강조하는 주석

대수롭지 않다고 여겨서 지우거나 수정하면

절대 안 되는 부분 강조

// trim() 처리 중요
// 문자열에 시작 공백이 있으면 다른 문자열로 인식됨
String listItemContent = match.group(3).trim()

 

 

(Good) 정보 제공

코드만으로도 충분하지만

빠르게 이해시킬 수 있는 주석도 좋다.

// kk:mm:ss EEE, MMM dd, yyyy 형식
Pattern password = Pattern.parse("\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*");

 

사람이 이해하기 쉬운 직관적인 정보 제공하는 것

assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b
assertTrue(a.compareTo(b) == 1); // a > b
assertTrue(a.compareTo(b) == -1); // a < b

 

---

📌 나쁜 주석

• 주절거리는 주석

• 같은 내용 반복

• 의무적으로 다는 주석

• 닫는 괄호에 다는 주석

• 오해할 여지가 있는 주석

• 위치 표시하는 주석

• 공헌자 및 저자 표시

 

 

(Bad) 주절거리는 주석

개발자 자신만 알 수 있는 내용

다른 사람들에게는 의도가 전해지지 않아서

모듈을 찾아보게 만든다.

ex) 상황을 설명하는 것인지, 나중에 처리한다는 것인지.

public void loadProperties() {
    try {
        string propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;
        ifstream propertiesStream(propertiesPath);
        loadedProperties.load(propertiesStream);
    } catch (IOException e) {
        // 속성 파일이 없다면 기본 값을 모두 메모리로 읽어 들였다는 의미다.
    }
}

 

 

(Bad) 같은 내용 반복하는 주석

코드 내용을 그대로 중복하는 주석은

주석 읽을 시간에 코드 읽는 게 더 빠르다.

// this.closed가 true일 때 반환되는 유틸리티 메서드
// 타임아웃에 도달하면 예외를 던진다.
void waitForClose(const long timeoutMillis) {
    if (!closed) {
        Sleep(timeoutMillis);

        if (!closed) {
            throw exception("MockResponseSender could not be closed");
        }
    }
}

 

 

(Bad) 의무적으로 다는 주석

만약 일하는 곳에서 보인다면

Convention을 논의할 볼 필요가 있다. 🤔

/*
* @param title CD 제목
* @param author CD 저자
* @param durationInMinutes CD 길이(단위: 분)
*/
void addCD(string title, String author, int durationInMinutes) {
cdList.emplace_back({title, author, durationInMinutes});
}

 

 

(Bad) 닫는 괄호에 사용하는 주석

중첩이 너무 많다면 내용을 줄일 수 있는지 고민해보고

그럼에도 중첩이 너무 많다면

어쩔 수 없이 사용되기도 한다.

int main(int argc, char** argv) {
    int lineCnt = 0;
    int charCnt = 0;
    int wordCnt = 0;
    try {
        while (...) {
            lineCnt++;
            charCnt += ...
        } //while


        cout << "wordCnt = " << wordCnt << endl;
        cout << "lineCnt = " << lineCnt << endl;
        cout << "charCnt = " << charCnt << endl;
    } // try
    catch (const exception& e) {
        cout << "Error:" << e.what() << endl;
    } //catch
} //main

 

 

 

(Bad) 모호한 정보

/*
모든 픽셀을 담을 만큼 충분한 배열로 시작 (필터 바이트를 더한다).
헤더 정보를 위해 200바이트를 더한다.
*/
this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];

• 필터 바이트란 무엇이고, "+1" 과 "*3" 어느 부분에 해당되는가?

• 헤더 정보는 몇 바이트이어야 하는가?

• 왜 "200"을 더해주었는가?

 

 

📌 클린 코드(Clean Code)란?

클린 코드(Clean Code)란?