코드 주석 작성 모범 사례

개발자에게 꼭 필요한 바이블인 스택오버플로우에 좋은 주석을 작성하기 위한 "코드 주석 작성 모범 사례" 글이 있어서 K식으로 정리해본다. 

 

주석은 프로그램을 개발자가 읽고 이해할 수 있게 도와주는 도우미 역할을 해준다. 읽기 좋은 코드는 주석이 필요없다와 같은 오만한 말도 있지만 개인적으로 동의하지 않는다. 코드를 읽는 다른 사람은 배경 지식과 IT 지식이 모두 다른 상태에서 코드만을 보고 프로그램을 이해하는 것은 이정표 없이 길을 찾으라는 말과 같으니까. 반대로 좋지 못한 나쁜 주석은 프로그램을 이해하는데 방해가 되며 차라리 없느니만 못한 결과를 초래하게 된다. 

 

그렇기 때문에 우리는 좋은 주석을 작성하기 위해 주의를 기울여야 한다. 

 

1. 주석에 코드를 담지 말라. 

 

if (x > 3) {
   …
} // if

이렇게 블록이 끝나는 중괄호에 주석을 추가하는 경우가 있는데 정말 필요할까? 

 

i = i + 1;         // Add one to i

// create a for loop // <-- comment
for // start for loop
(   // round bracket
    // newline
int // type for declaration
i    // name for declaration
=   // assignment operator for declaration
0   // start value for i

이런 주석을 작성하는 것은 필요하지 않다. 좀 전에 이정표라고 말했듯 길 자체를 주석에 넣을 필요는 없다. 

 

---

2. 주석 대신 명확한 코드를 작성하라.

 

나쁜 예)

private static Node getBestChildNode(Node node) {
    Node n; // best child node candidate
    for (Node node: node.getChildren()) {
        // update n if the current state is better
        if (n == null || utility(node) > utility(n)) {
            n = node;
        }
    }
    return n;
}

 

좋은 예)

private static Node getBestChildNode(Node node) {
    Node bestNode;
    for (Node currentNode: node.getChildren()) {
        if (bestNode == null || utility(currentNode) > utility(bestNode)) {
            bestNode = currentNode;
        }
    }
    return bestNode;
}

 

모든 코드를 주석을 대체할 만큼 작성할수는 없겠지만 이렇게 간단한 예도 있다. 주석을 작성하기 전에 코드를 수정해서 주석을 작성하지 않을 수 있다면 그렇게 하자. 

---

3. 주석을 작성하기 어렵다면 코드에 문제가 있을 수도 있다.

 

주석을 작성하려 하는데 작성하기가 애매하다~ 복잡하다~ 등의 문제가 있다면 코드에 문제가 있을 수 있다. SOLID 원칙을 위배한다던지 말이다. 

---

4. 주석은 혼란을 발생시키면 안된다.

 

어떤이는 주석을 코드에 추가하는 것을 하지 않았다고 하는데 수백줄의 코드에 `RIPJSB`라는 주석만을 추가했다고 하네요. 아무도 알아볼 수 없는 주석이었고 뜻은 `Rest In Peace Johann Sebastian Bach` 약어였다고 하죠. 

---

5. 주석에 단일 관용적 코드 설명을 피하라.

 

final Object value = (new JSONTokener(jsonString)).nextValue();
// Note that JSONTokener.nextValue() may return
// a value equals() to null.
if (value == null || value.equals(null)) {
    return null;
}

 

굳이 필요하지 않은 주석으로 보인다. 

 

if (b == true)

if (b)

 

위 코드를 아래 if(b) 로 변경 가능하지 않을까 생각이 드는데 null 체크를 하지 않기 위해 true와 비교를 하는 것으로 작성 된 코드였다. 아래의 코드보다 간단하지 않은가. 

 

if (b != null && b)

---

6. 복사한 코드라면 원본 소스 링크를 제공하자.

 

우리는 구글링을 통하여 많은 코드를 작성하는데 원본 링크를 포함하게 되면 다음 정보들을 얻을 수 있다. 

 

• 어떤 문제가 해결되고 있었는지
• 코드를 제공한 사람
• 솔루션이 권장되는 이유
• 작성자가 생각한 것
• 여전히 작동하는지 여부
• 어떻게 개선할 수 있는지

예를 들어 원본 링크를 제공할때는 아래처럼 하면 된다.

 

/** Converts a Drawable to Bitmap. via https://stackoverflow.com/a/46018816/2219998. */

 

이 원본 링크에서는 이런 정보를 얻을 수 있다. 

 

• 코드 작성자는 Stack Overflow에서 상위 3%에 속하는 Tomáš Procházka입니다.
• 한 주석 작성자는 이미 리포지토리에 통합된 최적화를 제공합니다.
• 또 다른 주석 작성자는 극단적인 경우를 피하는 방법을 제안합니다.

 

아래처럼 원본 링크를 찾기 어렵게 남기는 경우가 있는데 지양해야한다. ( 왜 숨기는 가? ) 

// Magical formula taken from a stackoverflow post, reputedly related to
// human vision perception.
return (int) (0.3 * red + 0.59 * green + 0.11 * blue);

 

단지 작동 원리도 이해하지 못하는 것을 마구 가져다 사용해선 안된다. 

---

7. 가장 유용한 외부 참조 링크를 포함한다.

 

// http://tools.ietf.org/html/rfc4180 suggests that CSV lines
// should be terminated by CRLF, hence the \r\n.
csvStringBuilder.append("\r\n");

 

다음 예시는 RFC 4180 표준이 RFC 7111에 의해 사양이 변경된 것을 알려주고 있어 가장 유용한 참조가 된다. 

---

8. 버그 수정 시 주석 추가

 

  // NOTE: At least in Firefox 2, if the user drags outside of the browser window,
  // mouse-move (and even mouse-down) events will not be received until
  // the user drags back inside the window. A workaround for this issue
  // exists in the implementation for onMouseLeave().
  @Override
  public void onMouseMove(Widget sender, int x, int y) { .. }

 

---

9. 주석에 미구현 내용을 작성하자.

 

// TODO(hal): We are making the decimal separator be a period, 
// regardless of the locale of the phone. We need to think about 
// how to allow comma as decimal separator, which will require 
// updating number parsing and other places that transform numbers 
// to strings, such as FormatAsDecimal

 

소수 구분 기호를 마침표로 처리하는 기능이지만 쉼표를 원하는 경우 소스를 수정해야합니다. 와 같이 todo 내용을 작성하고있다. 기술 부채를 해결하는데 도움이 된다. 

---

주석과 관련된 밈들

 

출처:  https://www.reddit.com/r/ProgrammerHumor/comments/8w54mx/code_comments_be_like/

 

 

출처:  https://www.reddit.com/r/ProgrammerHumor/comments/bz35nh/whats_a_comment/

 

 

 

 

 

원본 글 : https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/