클린코드 챌린지 DAY4 (2024.06.27)

TIL (Today I Learned)

2024.06.27

✔️ range

4장 주석

✔️ memory

• 나쁜 코드에 주석을 달지 마라. 새로 짜라. -p68
  • 시작부터 안되겠는데..
  • 주석은 나쁜 코드를 보완하지 못한다. 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
• 좋은 주석 -p70~p74
  • 법적인 주석
  • 정보를 제공해 주는 주석
  • 의도를 설명하는 주석
  • 의미를 명료하게 밝히는 주석
  • 결과를 경고하는 주석
  • TODO 주석
  • 중요성을 강조하는 주석
• 나쁜 주석 -p75~
  • 주절거리는 주석
  • 같은 이야기를 중복하는 주석
  • 오해할 여지가 있는 주석
  • 의무적으로 다는 주석
  • 이력을 기록하는 주석
  • 있으나 마나 한 주석
  • 함수나 변수로 표현할 수 있다면 주석을 달지 말자

✔️ learn

좋은 주석

✏️ 법적인 주석

회사가 정립한 구현 표준에 맞춰 법적인 이유로 특정 주석을 명시

// 테스트 중인 Responder 인스턴스를 반환한다. protected abstract Responder responderInstance();
// Copyright (C) 2003, 2004, 2005 by Object Montor, Inc. All right reserved. // GNU General Public License

✏️ 정보를 제공해주는 주석

정보를 주석으로 제공

// 테스트 중인 Responder 인스턴스를 반환
protected abstract Responder responderInstance();

✏️ 의도를 설명하는 주석

함수를 이미 알고 있으므로 어떠한 의도로 정렬 기준을 설정했는지 설명해 주면 도움이 된다.

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

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

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

✏️ 결과를 경고하는 주석

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

✏️ TODO 주석

앞으로 할 일을 주석

// TODO-MdM 현재 필요하지 않다.
// 체크아웃 모델을 도입하면 함수가 필요 없다.
protected VersionInfo makeVersion() throws Exception {
    return null;
}

✏️ 중요성을 강조하는 주석

자칫 대수롭지 않다고 여겨질 뭔가의 중요성을 가져오기 위해서 주석 사용

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

---

나쁜 주석

✏️ 주절거리는 주석

특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 주석을 다는 경우라면 시간낭비

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");
        }
    }
}

✏️ 오해할 여지가 있는 주석

중복이 많으면서도 오해할 여지

✏️ 의무적으로 다는 주석

모든 함수에 Javadocs를 달거나 모든 변수에 주석을 달아야 한다는 규칙은 어리석기 그지없다.

/**
 *
 * @param title CD 제목
 * @param author CD 저자
 * @param tracks CD 트랙 숫자
 * @param durationInMinutes CD 길이(단위: 분)
 */
public void addCD(String title, String author, int tracks, int durationInMinutes) {
    CD cd = new CD();
    cd.title = title;
    cd.author = author;
    cd.tracks = tracks;
    cd.duration = durationInMinutes;
    cdList.add(cd);
}

✏️ 이력을 기록하는 주석

* 변경 이력 (11-Oct-2001부터)
* ------------------------------------------------
* 11-Oct-2001 : 클래스를 다시 정리하고 새로운 패키징
* 05-Nov-2001: getDescription() 메소드 추가
* 이하 생략

✏️ 있으나 마나 한 주석

/*
 * 기본 생성자
 */
protected AnnualDateRule() {

}

✏️ 함수나 변수로 표현할 수 있는 주석

// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if(smodule.getDependSubsystems().contains(subSysMod.getSubSystem())

vs

ArrayList moduleDependees = smodule.getDependSubsystem(); 
String ourSubSystem = subSysMod.getSubSystem(); 
if(moduileDependes.contains(ourSubSystem))

✏️ 주석으로 처리한 코드

//    public void run(ApplicationArguments args) throws Exception {
//        StopWatch stopWatch = new StopWatch();
//        stopWatch.start();
//
//        stopWatch.stop();
//    }

✏️ html 주석

HTML 주석은 혐오란다. 나도 그렇게 생각함

✔️ impression

함수나 변수로 표현할 수 있다면 주석을 달지 말자

주석이라는 것이 항상 꼭 필요하다고만 생각을 했는데 변수나 함수들을 굳이 사용해 줄 필요는 없었구나...

코드를 보면 다양한 주석들..

 

vscode에 //나 /**/ 를 검색했을 때 정말 다양한 주석들이 많았다. 책과 같이 이상한 주석들도 많았고, 좋은 주석들도 있었는데 상황에 맞게 잘 사용해야겠다.

✔️ My favorite book-TIL

minhyeok_choi님의 TIL : slack에 1등으로 올리셨음 🥇
wltjs8958님의 TIL : 피드에 계속 보였음 🔍
담님의 TIL : 1일 차 하시고 안 보여서 언급 😎