Comments Rules

작성일 | In |

클린코더스 - 백명석님 강의를 보고 작성한 글입니다.

Comments

조직이 일정수준의 크기가 되면 문서화를 요구한다. 하지만 별도의 문서를 작성하는 것은 반대!!

처음에는 별도의 문서가 있어도 괜찮을거라고 생각이 들었는데 강의를 듣다보니 생각이 바뀌었다. 코드에 대한 설명을 코드 자체로 설명하는 것이지 별도의 문서로 설명한다는 것은 아니라고 한다. 별도의 문서가 필요하다는 말은 해당 코드가 Coding Standard의 예로 적합하지 않다는 뜻이 된다.
Comments 작성을 강요하면 프로그래머는 필요해서가 아니라 해야하므로 Comment를 작성하게된다.
그리고 이런 Comments는 무의미하고, 무시당하기 십상이다. 너무해ㅠ
Comments를 보는사람이 감사하는 마음이 생겨야 좋은 Comments이다.

모든 Comments는 당신의 코드가 ‘제대로 표현되고있지않다’라는 실패의 상징이다.

이 말은 좀 충격이었다. 지금까지 사람들에게 내 코드를 이해시키기위해 주석을 열심히 써왔는데… 차라리 이 노력을 코드표현력에 쏟을걸 하는 생각이 들었다.

그렇다면 Comments를 꼭 써야하는 상황에서의 좋은 Comments 그리고 나쁜 Comments는 무엇일까?

좋은 Comments

Legal Comments

  • 법적인 문제가 쓰여져있는 Comments
  • Ex) LICENSE 문제

Informative Comments

1
2
3
4
...
// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timePattern = Pattern.compile("\\d*:\\d*:\\d* \\w*. \\w* \\d*, \\d*");
...

  • 예를 들면 정규식을 사용할 때 이 패턴이 어떤 패턴인지 설명해주는 그런 정보를 제공하는 Comments

Warning of Consequences

1
2
3
// don't run unless you have some time to kill
@Test
public void readReallyBigFile() {...}

  • 코드에 관해서 경고할 때

TODO Comments

  • TODO(해야할 일에 관한 Comment)
    Public API Documentation

나쁜 Comments

Mumbling

  • 주저리주저리 써놓은 Comments들

Redundant Explanations

1
2
// The Child Containers belong to this container, keyed by name
private Map<String, Child> children = new HashMap<String, Child>();

  • 코드한줄만 봐도 뻔히 알 수 있는 내용인데 굳이 Comment에서 중복되게 다시 설명하고 있는 Comment

Mandated Redundancy

1
2
3
4
5
6
7
8
/**
 *
 * @param dateIn input date
 * @return formatted string
 */
 public static String convertDateFormat(String dateIn) {
     ...
 }

  • IDE에서 자동으로 생기는 Comment

Journal Comments

1
2
3
4
5
/**
 * 변경이력
 * 2018.11.01 : 생성
 * 2018.11.05 : convertDateFormat 메소드 구현 ...
 */

  • 코드의 변경이력을 써놓은 Comment

Noways Comments

1
2
3
4
5
6
7
8
public class DateFormatUtils {
    /**
     *  default constructor
     */
     public DateFormatUtils() {
         ...
     }
}

  • 누가봐도 default 생성자인데 굳이 위에 생성자라고 Comment를 작성하는 것처럼 너무 말도 안되게 뻔한 Comments (절대 해선안된다!!)

Big Banner Comments

1
2
3
4
5
6
7
8
public class DateFormatUtils {
    /************************
     * instance variables   *
     ************************/
     private int day;
     private int date;
     ... 
}

  • 잘보이게 하려고 특수문자로 도배해놓은 Comment

Closing Brace Comments

1
2
3
4
5
for (int i = 0; i< length; i++) {
    if(...) {

    } //end of if
} //end of for

  • loop의 끝과 Method의 끝 등등 코드블록 끝을 표시해놓은 Comment

Attribution Comments

1
2
3
4
// add by jm
private class Child {

}

  • 누가 작성했는지 써놓은 Comment, 굳이 코드에 써놓을 필요가 없다.

HTML in Comments

  • HTML 코드로 Comment 작성 (javadoc 작성을 위해서 이렇게 하는 사람들이 있다고한다.)

Non-Local Information

  • local이 아닌 멀리 떨어진 곳의 코드를 설명하는 Comments는 Comments와 무고나하게 변경될 수 있다.
0%