[Javascript] 스타일 가이드#2

자바스크립트 스타일 가이드

7. 주석

• 주석을 자주 사용하면 다른 사람이 코드를 이해하는 데 도움이 된다
  • 이해하기 어려운 코드
  • 에러로 오해하기 쉬운 코드
  • 로직이 명확하지 않은 특정 브라우절르 위한 코드
  • 문서 생성에 필요한 객체, 메서드, 프로퍼티

7-1. 한 줄 주석

• 코드 한 줄 이나 코드에 관련된 줄을 주석 처리할 때 사용
  • 한단의 코드를 설명하기 위해 독립된 줄에 주석을 작성
  • 주석 앞의 코드를 설명하기 위해 줄 끝에 주석을 작성
  • 한 줄 주석으로 여러 줄의 코드를 주석 처리

좋은 예
if(condition){

    // 이 줄이 실행되었다면 모든 보안 검사가 통과되었다는 의미입니다.
    allowed();
}

나쁜 예 : 이전 줄에 빈줄이 입력되지 않음
if( condition){
    // 이 줄이 실행된다면 모든 보안 검사가 통과되었다는 의미입니다.
    allowed();
}

나쁜 예 : 잘못된 들여쓰기
if(condition){
// 이 줄이 실행된다면 모든 보안 검사가 통과되었다는 의미입니다. 
    allowed();
}

-   나쁜 예 : 이 주석은 여러 줄 주석으로 처리해야한다.
-   이후에 나오는 코드는 상당히 복잡하다. 코드에 대해 설명합니다.
-   여기서 확인할 부분은 condition 값이 true 인지 체크하여 허용된 사용자만이
-   들어올 수 있도록 하는 것이다.
-   변경될 수 있고, 세션이 살아있는 동안 언제든지 변할 수 있다.

if(condition){
    // 이 줄이 실행된다면 모든 보안 검사가 통과되었다는 의미입니다.
    allowed();
}

-   줄 끝에 입력하는 한 줄 주석은 코드 끝을 기준으로 최소 한 단계 들여쓰기한 후 입력

좋은 예 :  
    var result = something + somethingElse; // somethingElse는 절대 null이면 안된다

나쁜 예 : 코드와 주석 사이의 공백이 충분하지 않다.  
    var result = something + somethingElse;// somethingElse는 절대 null이면 안된다.


좋은 예 :  
    if (condition){

    doSomething();  
    thenDoSomethingElse();

    };

7-2. 여러 줄 주석

• 코드에 더 상세한 설명이 필요할 때 사용합니다.
  여러 줄 주석은 최소 세 줄에 걸쳐 작성되어야 한다

• 첫 번째 줄은 /* 입력. 이 줄에는 그 외 다른 텍스트가 있으면 안된다.

• 다음 줄부터는 *를 입력하는데 첫 번째줄의 *과 열을 맞춘다. 여기서부터 텍스트 입력하기

• 마지막 줄은 */입력, 이전 줄과 열을 맞춘다. 그 외 다른 텍스트가 있으면 안된다.

좋은 예 :

if(condition){

    /*
        * 이 줄이 실행된다면
        * 모든 보안 검사가 통과되었다는 의미입니다.
    */
    allowed();
}

나쁜 예 : 주석 앞에 빈칸 없음

if(condition){
    /*
        * 이 줄이 실행된다면
        * 모든 보안 검사가 통과되었다는 의미입니다.
    */
    allowed();
}

나쁜 예 : * 뒤에 공백 없음

if(condition){

    /*
        *이 줄이 실행된다면
        *모든 보안 검사가 통과되었다는 의미입니다.
    */
    allowed();
}

나쁜 예 : 잘못된 들여쓰기

if(condition){

    /*
    * 이 줄이 실행된다면
    * 모든 보안 검사가 통과되었다는 의미입니다.
    */
    allowed();
}

나쁜 예 : 꼬리 주석은 여러 줄 주석으로 작성하지 않음
if(condition){

    allowed(); /* somethingElse는 절대 null이 아님 */
}

7-3. 주석 어노테이션

• 주석의 어노테이션으로 코드에 추가적인 설명을 하기 위해 사용합니다.
  어노테이션은 한 단어이며, 그 뒤에 콜론이 붙는다. 어노테이션은 다음 형식으로 작성합니다

1. TODO

• 코드를 아직 다 작성하지 않았음을 의미, 다음에 작업할 내용에 대한 정보가 반드시 있어야 한다.

2. HACK

• 임시변통의 방법을 사용한 코드를 의미, 핵을 왜 사용했는지에 대한 정보가 반드시
  있어야 한다. 나중에 더 나은 방법으로 문제를 해결할 수도 있다.

3. XXX

• 코드에 문제가 있어 가능한 빨리 수정해야 함을 의미

4. FIXME

• 코드에 문제가 있어 곧 수정해야 함을 의미. XXX 보다는 덜 중요

5. REVIEW

• 변경 가능성이 있어 리뷰가 필요한 코드를 의미

좋은 예 

// TODO : 더 빠르게 처리하는 방법을 찾아보겠습니다
dosomeThing();

/*
 * HACK : IE를 위한 코드입니다. 나중에 시간이 날 때
 * 다시 한 번 보겠습니다. 이 코드는 버전 1.2가 되기 전까지
 * 반드시 수정되어야 합니다.
*/

if(document.all){
    dosomeThing();
}

// REVIEW : 더 좋은 방법이 있을까요?
if(document.all){
    dosomeThing();
}

나쁜 예 : 주석 공백이 잘못 되어 있음
// TODO : 빠르게 처리하는 방법을 찾아보겠습니다.
dosomeThing();

나쁜 예 : 주서은 코드와 들여쓰기가 단계가 같아야 한다

// REVIEW: 더 좋은 방법이 있을까요?
if (document.all){
    dosomething();
} 

---

참고문헌 : 읽기좋은 자바스크립트 코딩 기법 / Maintainable Javascript / 니콜라스 자카