들어가기 앞서
이 글은 개발자 필독서인 클린 코드를 읽으며 습득한 내용을 정리한 글입니다. 모든 출처는 해당 저서에 있습니다.
- 개발자에게 프로그래밍 언어를 조율해 의도를 표현할 능력이 있다면, 주석은 필요하지 않을 것이다.
- 코드로 의도를 표현하지 못해 주석을 사용한다. 즉, 주석은 실패를 의미한다.
- 주석이 필요한 상황에 처한다면, 코드로 의도를 표현할 방법은 없는지 찾아봐야 한다.
- 주석은 오래될수록 코드에서 멀어지며, 완전히 그릇될 가능성이 커진다. 주석을 유지하고 보수하기란 현실적으로 불가능하기 때문이다.
- 코드는 변화하고 진화하지만, 주석은 코드를 따라가지 못한다.
- 주석이 필요 없게끔, 코드를 정리하고 표현력을 강화하는 방향으로 에너지를 쏟는 편이 낫다.
- 부정확한 주석은 더이상 지킬 필요가 없는 규칙이나 지켜서는 안 되는 규칙을 명시하곤 한다.
- 코드만이 정확한 정보를 제공하는 유일한 출처이기 때문에, 주석을 가능한 줄이도록 노력해야 한다.
1. 주석은 나쁜 코드를 보완하지 못한다
- 코드에 주석을 추가하는 일반적인 이유는 코드 품질이 나쁘기 때문이다.
- 표현력이 풍부하고 깔끔하며 주석이 거의 없는 코드를 작성하는 것이 낫다.
2. 코드로 의도를 표현하라
코드로 대다수 의도를 표현할 수 있다. 주석으로 달려는 설명을 함수로 만들어 표현하는 방법이 존재한다.
🖥️ 개선 전
// 직원에게 복지 혜택을 받을 자격이 있는지 검사한다.
if ((employee.flags & HOURLY_FLAG) && (employee.age > 65))🖥️ 개선 후
if (employee.isEligibleForFullBenefits())3. 좋은 주석
주석을 달지 않는 것이 가장 좋은 방법이지만, 주석이 필요하거나 유익한 경우가 존재한다.
3.1 법적인 주석
- 회사가 정립한 구현 표준에 법적인 이유로 특정 주석을 넣으라고 명시하는 경우
- 원시 파일 첫 머리에 저작권 정보와 소유권 정보 명시
- 가능하다면 표준 라이선스나 외부 문서를 참조하는 방법을 추천한다.
3.2 정보를 제공하는 주석
-
주석으로 기본적인 정보를 제공하면 편리하고 유용하나, 가능하다면 함수 이름에 정보를 담는 편이 낫다.
🖥️ 개선 전
// 테스트 중인 Responder 인스턴스를 반환한다. protected abstract Responder responderInstance();🖥️ 개선 후
// kk:mm:ss EEE, MMM dd, yyyy 형식이다. Pattern timeMatcher = Pattern.compile("\\d*:\\d*:\\d* \\w* \\d* \\d*"); -
이왕이면 클래스를 만들어 코드를 옮겨주어 주석을 없애는 방법을 추천한다.
🖥️ 시각과 날짜를 변환하는 클래스
public class DateTimeParser { private static final DateTimeFormatter DATE_TIME_FORMATTER = DateTimeFormatter.ofPattern("kk:mm:ss EEE, MMM dd, yyyy"); public static LocalDateTime parseDateTime(String dateTimeText) { try { return LocalDateTime.parse(dateTimeText, DATE_TIME_FORMATTER); } catch (DateTimeParseException e) { System.err.println("Failed to parse date-time: " + e.getMessage()); return null; } } }🖥️ main
String exampleDateTime = "14:30:00 Sun, Jul 27, 2024"; LocalDateTime dateTime = DateTimeParser.parseDateTime(exampleDateTime);
3.3 의도를 설명하는 주석
때때로 주석은 결정에 깔린 의도까지 설명한다.
🖥️ 예시 1
public int compaerTo(Object o) {
if(o instanceof WiliPagePath) {
WikiPagePath p = (WikiPagePath) o;
String compressedName = StringUtil.join(names, "");
String compressedArgumentName = StringUtil.join(p.names, "");
}
return 1; // 옳은 유형이므로 정렬 순위가 더 높다.
}🖥️ 예시 2
public void testConcurrentAddWidgets() throws Exception {
WidgetBuilder widgetBuilder = new WidgetBuilder(new Class[]{BoldWidget.class});
String text = "'''bold text'''";
ParentWidget parent = new BoldWidget(new MockWidgetRoot(), text);
AtomicBoolean failFlag = new AtomicBoolean();
failFlag.set(false);
// 스레드를 대량 생성하는 방법으로 어떻게든 경쟁 조건을 만들려고 시도한다.
for (int i = 0; i < 25000; i++) {
WidgetBuilderThread widgetBuilderThread = new WidgetBuilderThread(WidgetBuilder, text, parent, failFlag);
Thread thread = new Thread(widgetBuilderThread);
thread.start();
}
assertEquals(false, failFlag.get());
}3.4 의미를 명료하게 밝히는 주석
-
애매한 인수나 반환 값은 그 의미를 읽기 좋게 표현하면 이해하기 쉬워진다.
-
인수나 반환 값이 표준 라이브러리나 변경하지 못하는 코드에 속한다면 의미를 명료하게 밝히는 주석이 유용하다.
-
주석이 올바른지 검증하기 쉽지 않기 때문에 그릇된 주석을 달아놓을 확률이 높다. 그러므로 더 나은 방법이 없는지 고민하고 정확히 달도록 각별히 주의한다.
🖥️ 예시
public void testCompareTo() throws Exception { WikiPagePath a = PathParser.parse("PageA"); assertTrue(a.compareTo(a) == 0); // a == a }
3.5 결과를 경고하는 주석
주석으로 인해 실수를 예방할 수 있다.
🖥️ 예시 1
// 여유 시간이 충분하지 않다면 실행하지 마십시오.
public void _testWithReallyBigFile() {
writeLinesToFile(10000000);
response.setBody(testFile);
response.readyToSend(this);
String responseString = output.toString();
assertSubString("Content-Length: 1000000000", responseString);
assertTrue(bytesSent > 1000000000);
}🖥️ 예시 2
public static SimpleDateFormat makeStandardHttpDateFormat() {
// SimpleDateFormat은 스레드에 안전하지 못하다.
// 따라서 각 인스턴스를 독립적으로 생성해야 한다.
SimpleDateFormat df = new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss z");
df.setTimeZone(TimeZone.getTimeZone("GMT"));
return df;
}- 프로그램 효율을 높이기 위해 정적 초기화 함수를 사용하려는 실수 방지
3.6 TODO 주석
- TODO 주석은 프로그래머가 필요하다 여기지만 당장 구현하기 어려운 업무를 기술한다.
- 다만, 시스템에 나쁜 코드를 남겨놓는 핑계가 되어서는 안 된다.
- TODO로 떡칠한 코드는 바람직하지 못하다.
- 주기적으로 TODO 주석을 점검해 없애도 괜찮은 주석은 없애도록 한다.
3.7 중요성을 강조하는 주석
자칫 대수롭지 않다고 여겨질 무언가의 중요성을 강조하기 위해 사용하기도 한다.
🖥️ 예시
String listItemContent = match.group(3).trim();
// 여기서 trim은 정말로 중요하다. trim 함수는 문자열에서 시작 공백을 제거한다.
// 문자열에 시작 공백이 있으면 다른 문자열로 인식되기 때문이다.
new ListItemWidget(this, listItemContent, this.level + 1);
return buildList(text.substring(match.end()));3.8 공개 API에서 Javadocs
- 설명이 잘 된 공개 API는 개발자에게 상당히 유용하다.
- 공개 API를 구현한다면 반드시 훌륭한 Javadocs를 작성하도록 한다.
- Javadocs 역시 독자를 오도하거나, 잘못 놓이거나, 그릇된 정보를 전달할 가능성이 존재하기 때문에 주의해야 한다.
4. 나쁜 주석
4.1 주절거리는 주석
- 특별한 이유 없이 의무감으로 혹은 프로세스에서 하라고 하니까 마지못해 주석을 다는 것은 시간낭비다.
- 주석을 달기로 결정했다면 충분한 시간을 들여 퀄리티 좋은 주석을 달도록 노력한다.
- 이해가 안 되어 다른 모듈까지 뒤져야 하는 주석은 독자와 제대로 소통하지 못하는 주석으로 바이트를 낭비한다.
4.2 같은 이야기를 중복하는 주석
- 같은 코드 내용을 헤더에 달린 주석에서 중복하는 경우, 코드보다 주석을 읽는 시간이 더 오래 걸릴 수 있다.
- 주석이 코드보다 더 많은 정보를 제공하지 못하며, 코드보다 읽기가 쉽지 않아 독자가 함수를 제대로 이해할 수 없게 만든다.
- 코드만 지저분하고 정신없게 만들뿐 기록적인 목적에는 기여하지 못한다.
4.3 오해할 여지가 있는 주석
주석에 담긴 잘못된 정보로 인해 발생하는 이슈를 파악하느라 시간을 소모하게 된다.
🖥️ 예시
// this.close가 true일 때 반환되는 유틸리티 메소드다.
// 타임아웃에 도달하면 예외를 던진다.
public stnchronized void waitForClose(final long timeoutMillis) throws Exception {
if(!closed) {
wait(timeoutMillis);
if(!closed) {
throw new Exception("MockResponseSender could not be closed");
}
}
}this.closed가true로 변하는 순간에 함수가 반환되리라는 생각으로 함수를 호출하게 되어 본인의 코드가 비효율적으로 작동하는 이유를 찾느라 골머리를 앓게 됨
4.4 의무적으로 다는 주석
의무적으로 다는 주석은 아무런 가치가 없다. 코드를 복잡하게 만들며, 거짓말을 퍼뜨리고, 잘못된 정보를 제공할 여지를 만든다.
🖥️ 예시
/**
*
* @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);
}4.5 이력을 기록하는 주석
- 모듈 첫머리 주석은 지금까지 모듈에 가한 변경을 모두 기록하는 일조의 일지 혹은 로그가 된다.
- 예전에는 원시 코드 제어 시스템이 없었으므로 이러한 관례가 바람직했으나, 현재는 혼란만 가중하므로 완전히 제거하는 편이 낫다.
4.6 있으나 마나 한 주석
-
너무 당연한 사실을 언급하며 새로운 정보를 제공하지 못하는 주석은 있으나 마나 한 주석이다.
🖥️ 예시
/** * 기본 생성자 */ protected AnnualDateRule() {} /** 달 중 날짜 */ private int DayOfMonth; /** * 달 중 날짜를 반환한다. * * @return 달 중 날짜 */ public int getDayOfMonth() { return dayOfMonth; } -
개발자가 코드를 읽으면서 자동으로 주석을 건너뛰게 되어, 나중에는 코드와 주석이 불일치하게 된다.
🖥️ 예시 - startSending
private void startSending() { try { doSending(); } catch(SocketException e) { // 정상. 누군가 요청을 멈췄다. } catch(Exception e) { try { response.add(ErrorResponser.makeExceptionString(e)); response.closeAll(); } catch(Exception e1) { // 이게 뭐야! } } } -
있으나 마나 한 주석을 달기보다는 코드를 정리하고 개선하도록 한다.
🖥️ 예시 - startSending(리팩토링 결과)
private void startSending() { try { doSending(); } catch(SocketException e) { // 정상. 누군가가 요청을 멈췄다. } catch(Exception e) { addExceptionAndCloseResponse(e); } } private void addExceptionAndcloseResponse(Exception e) { try { response.add(errorResponder.makeExceptionString(e)); response.closeAll(); } catch(Exception e1) {} }
4.7 무서운 잡음
단지 문서를 제공해야 한다는 잘못된 욕심으로 탄생한 주석은 아무런 이익도 주지 못한다.
🖥️ 예시
/** The name. */
private String name;
/** The version. */
private String version;
/** The licenceName. */
private String licenceName;
/** The version. */
private String info;- 심지어 info의 경우,
ctrl+c,ctrl+v오류가 존재한다.
4.8 함수나 변수로 표현할 수 있다면 주석을 달지 마라
주석이 필요하지 않도록 코드를 개선하는 방향으로 개발하도록 한다.
🖥️ 개선 전
// 전역 목록 <smodule>에 속하는 모듈이 우리가 속한 하위 시스템에 의존하는가?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))🖥️ 개선 후
ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))4.9 위치를 표시하는 주석
- 너무 자주 사용하지 않는다면 배너는 눈에 띄며 주의를 환기한다.
- 반드시 필요할 때만, 아주 드물게 사용하도록 한다.
4.10 닫는 괄호에 다는 주석
-
중첩이 심하고 장황한 함수라면 의미가 있지만, 작고 캡슐화된 함수에는 잡음일 뿐이다.
-
그러므로 닫는 괄호에 주석을 다는 대신 함수를 줄이도록 한다.
🖥️ 예시 - 닫는 괄호에 주석을 달면 좋은 경우
public class wc { public static void main(String[] args) { BufferedReader in = new BufferedReader(new InputStreamReader(System.in)); String line; int lineCount = 0; int charCount = 0; int wordCount = 0; try { while ((line = in.readLine()) != null) { lineCount++; charCount += line.length(); String words[] = line.split("\\W"); wordCount += words.length; } //while System.out.println("wordCount = " + wordCount); System.out.println("lineCount = " + lineCount); System.out.println("charCount = " + charCount); } //try catch (IOException e) { System.err.println("Error:" + e.getMessage()); } //catch } //main }
4.11 공로를 돌리거나 저자를 표시하는 주석
오랫동안 코드에 방치되어 부정확하고 쓸모없는 정보로 변하기 일쑤이므로, 소스 코드 제어 시스템에 저장하는 편이 낫다.
4.12 주석으로 처리한 코드
- 주석으로 처리된 코드는 다른 사람들이 지우기를 주저하여 쓸모없는 코드가 쌓여가게 된다.
- 이유가 있어 남겨놓았으리라고, 중요하니까 지우면 안 된다고 생각한다.
- 원시 코드 제어 시스템이 코드를 기억하기 때문에, 주석으로 처리하지 말고 코드를 삭제하도록 한다.
4.13 HTML 주석
도구로 주석을 뽑아 웹 페이지에 올릴거라면, 주석에 HTML 태그를 삽입하는 책임은 도구가 져야 한다.
4.13 전역 정보
-
주석을 달 때 근처에 있는 코드만 기술하고, 시스템 전반적인 정보를 기술하지 않도록 한다.
- 특히, 바로 아래 함수가 아니라 시스템 어딘가에 있는 다른 모듈에 대해 설명하는 경우, 코드가 변해도 주석이 변하리라는 보장이 없다.
🖥️ 예시
/** * 적합성 테스트가 동작하는 포트: 기본값은 <b>8082</b>. * * @param fitnessePort */ public void setFitnessePort(int fitnessePort) { this.fitnessePort = fitnessePort; }
4.14 너무 많은 정보
주석에 흥미로운 역사나 관련 없는 정보를 장황하게 늘어놓지 않도록 한다. 이는 독자에게 불필요하며 불가사의한 정보일 뿐이다.
4.15 모호한 관계
-
주석과 주석이 설명하는 코드는 둘 사이 관계가 명백해야 한다.
-
주석을 다는 이유는 코드만으로 설명이 부족해서인데, 주석 자체가 다시 설명을 요하는 것은 역할을 제대로 수행하지 못하고 있단 뜻이다.
🖥️ 예시
/* * 모든 픽셀을 담을 만큼 충분한 배열로 시작한다(여기에 필터 바이트를 더한다). * 그리고 헤더 정보를 위해서 200바이트를 더한다. */ this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];- 필터 바이트란 무엇인지, 한 픽셀이 한 바이트인지, 200을 추가하는 이유는 무엇인지 등 모호한 부분들이 존재한다.
4.16 함수 헤더
짧고 한 가지만 수행하며 이름을 잘 붙은 함수가 주석으로 헤더를 추가한 함수보다 낫다.
4.17 비공개 코드에서 Javadocs
- 공개하지 않을 코드(시스템 내부에 속하는 클래스와 함수)라면 Javadocs를 생성하지 않도록 한다.
- 유용하지 않을 뿐만 아니라 요구 형식으로 인해 코드가 보기 싫고 산만해진다.
📖 참고
- 로버트 C. 마틴, 『Clean Code 클린 코드 애자일 소프트웨어 장인 정신』, 박재호·이해영 옮김, 케이앤피북스(2010), p97-119.
기쁘게 코딩하고 싶은 백엔드 개발자