클린코드 - 주석

주노·2022년 11월 2일

4장 cleancode 주석

클린코드

목록 보기

2/5

서론

지난 시간에 이어 CleanCode에 대해 계속해서 정리해보자.

주석

어떤 일이 있어도 주석을 절대 사용하면 안된다. 라고 말할정도로 이 장에서는 주석을 사용할 이유가 없음을 설명하고있다.

정확히 말하자면 프로그래머가 실제로 주석을 지속적으로 관리하는 시간보다 클린코드를 고민하는 시간이 더 가치있다는 말이다.

주석은 코드의 내용을 즉각 반영하지 않기 때문에 향후 주석 내용이 코드를 정말 잘 설명하고있는지 의심하며 혼란을 가중시킨다.

정말 주석을 써도 괜찮은 경우가 있지 않을까 라며 스스로를 설득해볼 생각이 있다면 한번 아래 내용을 읽어보며 자신이 생각했던 모든 경우가 코드의 의미를 모호하게 만드는 주 원인이 되고 있음을 알게 될 것이다.

나쁜주석

대다수의 주석은 나쁜 주석인 경우가 허다하다.
이에 대한 안좋은 예시들을 나열한다.

주절거리는 주석

혼자 주절거리는 내용은 다른사람에게 의미를 전달하지 못하거나 대부분 코드로 의미를 나타낼 수 있는 부분이다.

public boolean register(SignRequest request) throws Exception {
        try {
            Member member = Member.builder()
                    .account(request.getAccount())
                    .password(passwordEncoder.encode(request.getPassword()))
                    .nickname(request.getNickname())
                    .name(request.getName())
                    .email(request.getEmail())
                    .build();

            member.setRoles(Collections.singletonList(Authority.builder().name("ROLE_USER").build()));

            memberRepository.save(member);
        } catch (Exception e) {
            // member를 저장하는 과정에서 잘못된 동작이 일어났을 때 Exception이 발생한다.
            System.out.println(e.getMessage());
            throw new Exception("잘못된 요청입니다.");
        }
        return true;
    }

같은 이야기를 하는 주석

이미 함수만으로 의미를 충분히 전달했으나 중복된 내용을 주석으로 다시 설명하고있다.

// 토큰의 JWS 정보를 Decoding하여 사용자 계정을 얻는다.
public String getAccount(String token) {
    return Jwts.parserBuilder()
            .setSigningKey(secretKey)
            .build().parseClaimsJws(token)
            .getBody()
            .getSubject();
}

오해할 여지가 있는 주석

의무적으로 다는 주석

모든 함수에 javadocs 혹은 변수에 주석을 달아야하는 규칙은 매우 어리석다.
되려 코드만 헷갈리게만들어 잘못된 정보를 제공할 여지만 만든다.

1주차 과제를 수행하던 내 모습을 저격하는 글이다..🥹

/**
 * 주어진 페이지의 각 자리수 합을 구한다.
 * @param page 페이지
 * @return 페이지의 각 자리수 합을 반환한다.
 */
 private static int getPageSum(Integer page) {
	String str = page.toString();
 	int result = 0;
 	for (int i = 0; i < str.length(); i++) {
    	result += str.charAt(i) - '0';
    }
	return result;
}

/**
* 주어진 페이지의 각 자리수 곱을 구한다.
* @param page 페이지
* @return 페이지의 각 자리수 곱을 반환한다.
*/
private static int getPageMultiple(Integer page) {
    String str = page.toString();
    int result = 1;
    for (int i = 0; i < str.length(); i++) {
        result *= str.charAt(i) - '0';
    }
    return result;
}

있으나 마나 한 주석

여기까지 읽었으면 당연하겠지만 있으나 마나 한 주석은 필요 없다.
아니 없어야한다.

// 기본생성자
public Account() {}

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

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

이 코드에서 주석을 없애면

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourS

저자를 표시하는 주석

우리는 Git과 같은 형상관리 프로그램을 사용하고 있기 때문에 이런 내용은 형상관리 프로그램에게 맡기도록하자.

주석으로 처리한 코드

주석으로 처리한 코드는 다음 사람이 읽었을 때 지우기 망설여진다.
이유가 있어 남겨놓은 것 같기 때문이다.

위에서 말했듯이 우리는 형상관리 프로그램을 사용한다. 그냥 삭제해도 복원할 수 있으니 굳이 주석처리해둘 이유가 없다.

HTML 주석

Javadoc의 내용을 뽑아서 웹에 올릴 용도가 아니라면 전혀 사용할 이유가 없다.
가독성만 나빠진다.

모호한 관계

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

위에서 말하는 필터 바이트가 무엇을 의미하는지 한눈에 들어오지않는다.
+1을 말하는건지 *3을 말하는건지...

코드를 설명하기위한 주석이 다시 설명을 요구하니 이상한 현상이다.

비공개 코드의 javadocs

공개 API를 만들것이 아니라면 javadocs는 되려 코드가 지저분해지는 원인이 되기 마련이다.

좋은 주석?

때로는 주석을 사용해야할 경우도 있다.
이 내용 외에는 대부분 주석을 사용할 이유를 찾기가 어렵다.
하지만 정말로 좋은 주석은 주석을 달지 않을 방법을 찾아낸 주석이다라는 말을 잊지말자.

법적인 주석

회사의 표준에 맞춰 법적인 이유로 특정 주석을 넣을 수 있다.
네이버의 오픈소스 가이드를 확인하면 오픈소스를 사용할 때도 저작권 및 라이센스에 대한 주석을 사용하는 것을 볼 수 있다.

jQuery 라이센스 사용 예시
/*!
 * jQuery UI Datepicker 1.10.4
 * http://jqueryui.com
 *
 * Copyright 2014 jQuery Foundation and other contributors
 * Released under the MIT license.
 * http://jquery.org/license
 *
 * http://api.jqueryui.com/datepicker/
 *
 * Depends:
 *	jquery.ui.core.js
 */

정보를 제공하는 주석

기본적인 정보를 주석으로 제공하면 편리한 경우가 있다.

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

위 주석은 코드의 정규표현식의 의미를 나타내고자 사용되었다.
하지만 이왕이면 시각과 날짜를 변환하는 클래스를 만들어 코드를 옮겨주는것이 더 깔끔하고 주석도 필요없어진다.

어디까지나 있어야하는 주석에 대한 이야기가 아니라 이정도는 봐줄만하다 정도의 주석에 대한 이야기를 하고있다. 결국엔 주석이 없는 상황이 더 좋다는 이야기다 😇

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

간혹 인수나 반환값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용해진다.

public void test {
...
assertTrue(a.compoareTo(a) == 0); // a == a
assertTrue(a.compoareTo(a) != 0); // a != a
assertTrue(a.compoareTo(ab) == 0); // a == ab
assertTrue(a.compoareTo(ab) == -1); // a < ab
assertTrue(a.compoareTo(ab) == 1); // a > a
,,,
}

물론 이 과정조차도 그릇된 주석을 달아둘 위험이 높다.
주석이 올바른지 검증하기 쉽지 않다. 위와같은 주석을 달 때는 더 나은 방법이 없는지 고민하고 정확하게 달도록 각별히 유의해야한다.

결과를 경고하는 주석

때로는 경고하는 주석이 도움이 되기도 한다.

public static SimpleDateFormat makeStandardHttpDateFormat() {
	// SimpleDateFormat은 Thread Safe하지 못하다.
    // 따라서 각 인스턴스를 독립적으로 생성해야한다.
    
    SimpleDateFormat df = new SimpleDateFormat("eee, dd MMM yyyy HH:mm:ss z");
    df.setTimeZone(TimeZone.getTimeZone("GMT"));
    return df;
}

어떤 개발자가 프로그램 효율을 높이기 위해 정적 초기화 함수를 사용하려고 했을 때 위 주석을 보면서 실수를 면할 수 있다는 예시다.

TODO

앞으로 해야할 일을 TODO 주석으로 남겨두면 편하다.

IntelliJ 에서는 다음과 같이 TODO가 붙어있는 주석들에 대해 탐색하기도한다.

하지만 TODO만 가득한 프로젝트라면 별로 보기 좋지 않을것이다.
처리할 수 있는 내용이라면 TODO에 해당하는 내용은 가급적 빠르게 처리해주는것이 좋다.

중요성을 강조하는 주석

위에서 말한 결과를 경고하는 주석과 비슷한 맥락으로 다가올 수 있다.
자칫 대수롭지 않게 넘어갈 수 있지만 중요한 내용에 대해서 주석을 남겨둘 수 있다.

String listItemContent = match.group(3).trim();
// trim이 중요하다!! trim은 문자열에서 공백을 제거한다.
// 문자열에 시작 공백이 존재할 시 다른 문자열로 인식되기 때문에 trim을 사용한다.
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));