자바스크립트 코딩 컨벤션(스타일 가이드)

---

이 글은 PC 버전 TISTORY에 최적화 되어있습니다.

서론

 이 글은 필자가 속해 있는 팀의 코딩 컨벤션(스타일 가이드)를 맞추기 위해 '더글라스 크락포드의 자바스크립트 코드 컨벤션'을 참고하여 작성한 것 입니다. 무조건 이 규칙들이 좋은 것은 아니니, 팀원들의 규칙들을 잘 통합하여 각자 팀만의 코딩 컨벤션을 적용하길 권장합니다. 

1. 코딩 컨벤션(스타일 가이드)가 필요한 이유

2. 들여쓰기

3. 연산자

4. 괄호

5. 주석

6. 기본 리터럴

7. 객체 리터럴

8. 변수 선언

9. 함수 선언

10. 문장 규칙

11. 가독성을 위한 공백

1. 코딩 컨벤션(스타일 가이드)가 필요한 이유

  대학 시절, 컴공과를 다니던 황OO군은 아무것도 없는 공백에 필요한 코드를 작성하여 '동작'을 목적으로 '성적'을 목적으로 의식의 흐름따라 코딩을 하였습니다.

예를 들면 이런 것 (내용도 내용이지만 필체마저 의식을 따라감)

  그렇게 잘 '동작'하는 코드를 통해 좋은 성적을 거두고 회사에 입사하게 되었습니다. 막상 와보니 교수님의 과제처럼 아무것도 없는 상태에서 뭔가를 구현하는 일은 생각보다 없습니다. 이미 선임이 짜놓은 코드를 기반으로 개발하게 된 것입니다. 문제는 여기서 발생합니다. "코드가 술술 읽히네 예술적이다." 라는 반응이 나오는 코드가 있는 반면 "이 코드 짠 XX 얼굴 한번 보고싶다." 라는 반응이 나오는 코드도 있습니다. 이 같은 문제를 해결하기 위해 나온 것이 자바스크립트 코딩 컨벤션(스타일 가이드)입니다. 

  실무에서는 새로운 코드 작성보다 '유지보수'에 더 많은 시간을 보낸다고 합니다. 대부분 이미 있는 코드에 새로운 코드를 추가하거나 수정합니다. 유지보수성이 좋게 코드를 작성했다면 작성자 본인 뿐만 아니라 다음 사람에게도 유지보수 시간을 단축할 수 있도록 도와줍니다. 다음은 '자바 언어를 위한 코드 컨벤션'에서 언급한 코딩 컨벤션의 중요성입니다.

- 소프트웨어 개발 시 드는 비용의 80%는 '유지보수'에 사용된다.

- 소프트웨어 개발 생명주기에서 최초 개발자가 끝까지 유지보수하는 경우는 거의 없다.

- 코딩 컨벤션은 소프트웨어 가독성을 향상시켜, 개발자가 새로운 코드를 더 빠르고, 완전하게 이해하게 함.

코딩 컨벤션의 필요성을 알았으니, 다음의 코딩 컨벤션 규칙들을 살펴보도록 하겠습니다.

2. 들여쓰기

  최근 에디터들은 자동으로 Enter를 치면 들여쓰기를 해주고 있습니다. 하지만 그것에 의존하지 말고 1번의 탭 또는 4번의 공백 둘 중 하나의 규칙을 습관적으로 적용합니다.

// 좋은 예
function test() {
    console.log('들여쓰기 테스트');
}

// 나쁜 예
function test() {
console.log('들여쓰기 테스트');
}

3. 연산자

3.1 연산자 삽입 시 공백 삽입 위치

 두 개의 피연산자와 함께 사용하는 연산자는 사용 시 연산자 앞 뒤에 공백을 한 칸씩 추가해주도록 합니다. 이는 연산자의 목적를 명확하게 보여주기 위함입니다. (주의, 단항 연산자는 붙여서 사용)

// 좋은 예
var isSuccess = (condition <= 10);

var i;
for (i = 0; i < 10; i++) {
    work();
}

// 나쁜 예
var isSuccess = (condition<=10);

var i;
for (i=0; i<10; i++) {
    work();
}

3.2 할당 연산자

 할당 연산자 사용시 할당 값이 비교 연산식이면 괄호로 감싸줍니다.

// 좋은 예
var isBaby = (age < 10);

// 나쁜 예
var isBaby = age < 10;

3.3 동등 연산자

 동등 비교를 할 때 타입 강제 변환의 위험이 있으면 무조건 ==, != 대신 ===, !==를 사용해줍니다.

// 좋은 예
console.log('1' === 1);

// 나쁜 예
console.log('1' == 1);

4. 괄호

여는 괄호 다음과, 닫는 괄호 이전에 공백은 없습니다.

// 좋은 예
var isBaby = (age <= 10);

// 좋은 예
var i;
for (i = 0; i < 10; i++) {
    work(hour, amount);
}

// 나쁜 예: 앞 뒤에 불필요한 공백 들어감
var isBaby = ( age <= 10 );

// 나쁜 예: 인자 사이에 불필요한 일 들어감
var i;
for (i = 0; i < 10; i++) {
    work( hour, amount );
}

5. 주석

5.1 한 줄 주석

• 하단의 코드를 설명하기 위해 독립된 줄에 주석 작성
• 주석 앞의 코드를 설명하기 위해 줄 끝에 주석 작성
• 여러 줄에 걸친 설명일 때는 사용하지 않는다.
• 독립된 줄에 한 줄 주석 작성 시에는 설명할 코드와 같은 단계 들여쓰기 사용하며, 이전 줄은 한 줄 비웁니다.

// 좋은 예
if (age > 20) {

    // 이 줄은 나이가 20살 이상일 때만 실행됩니다.
    showAdultMovie();
}

// 나쁜 예: 이전 줄에 공백이 없어 가독성이 떨어짐
if (age > 20) {
    // 이 줄은 나이가 20살 이상일 때만 실행됩니다.
    showAdultMovie();
}

// 나쁜 예: 주석의 들여쓰기가 설명할 주석과 단계가 다릅니다.
if (age > 20) {
    
// 이 줄은 나이가 20살 이상일 때만 실행됩니다.
    showAdultMovie();
}

// 나쁜 예: 한 줄 주석은 한 줄만 사용합시다.
// 이 코드는 만으로 나이가 20세 이상인 것이 아니고
// 그냥 20세 이상 아니아니 이게 아니고
// 아 아닙니다 만으로 나이가 20세 이상인
// 사람을 판별하기 위한 조건문입니다.
if (age > 20) {

    // 이 줄은 나이가 20살 이상일 때만 실행됩니다.
    showAdultMovie();
}

5.2 여러 줄 주석

• 첫 번째 줄은 여러 줄 주석을 여는 방법인 /*를 삽입하며, 다른 텍스트는 넣지 않는다.
• 그 다음 줄 부터는 *와 텍스트를 입력하는데 첫 째 줄의 *과 열을 맞춘다. *과 텍스트 사이에는 공백 하나를 넣어줍니다.
• 마지막 줄은 여러 줄 주석을 닫는 방법인 */를 삽입하며 다른 텍스트는 넣지 않는다.

// 좋은 예
if (age > 20) {

    /*
     * 이 코드는 만으로 나이가 20세 이상인 것이 아니고
     * 그냥 20세 이상 아니아니 이게 아니고
     * 아 아닙니다 만으로 나이가 20세 이상인
     * 사람을 판별하기 위한 조건문입니다.
     */
    showAdultMovie();
}

// 나쁜 예: 이전 줄에 공백이 없어 가독성이 떨어짐
if (age > 20) {
    /*
     * 이 코드는 만으로 나이가 20세 이상인 것이 아니고
     * 그냥 20세 이상 아니아니 이게 아니고
     * 아 아닙니다 만으로 나이가 20세 이상인
     * 사람을 판별하기 위한 조건문입니다.
     */
    showAdultMovie();
}

// 나쁜 예: *과 텍스트 사이에 공백이 없음
if (age > 20) {

    /*
     *이 코드는 만으로 나이가 20세 이상인 것이 아니고
     *그냥 20세 이상 아니아니 이게 아니고
     *아 아닙니다 만으로 나이가 20세 이상인
     *사람을 판별하기 위한 조건문입니다.
     */
    showAdultMovie();
}

5.3 주석 어노테이션

어노테이션은 코드에 추가적인 설명을 더합니다. 한 단어이며 그 뒤에 콜론이 붙습니다.

ㄱ. TODO : 코드를 다 작성하지 않음. 다음에 작성할 내용이 반드시 기술되어 있어야합니다.

ㄴ. HACK : 어거지(임시변통)으로 해결한 코드. 핵을 왜 사용했는지 정보가 있어야하며, 더 나은 방법으로 해결할 수 있음을 뜻합니다.

ㄷ. XXX : 코드에 문제가 있어 가능한 빨리 수정되야 함을 의미

ㄹ. FIXME : 코드에 문제가 있어 수정해야하지만 XXX보다는 덜 중요합니다.

ㅁ. 변경 가능성이 있거나 더 나은 방법이 있을 수 있음으로 리뷰가 필요한 코드를 의미합니다.

6. 기본 리터럴

• 문자열은 무조건 큰 따옴표로 묶습니다. 문자열을 \로 끊어 여러줄로 적지 않습니다.
  
• 숫자는 10진수 정수, 지수표현법을 이용한 정수, 16진수 정수, 부동 소수점을 이용한 정수만 사용하며, 소수점 앞 뒤에는 숫자가 최소 하나는 있어야 합니다. 8진수는 사용하지 않습니다.

// 좋은 예
var name = "황혁진";

// 나쁜 예
var name = '황혁진';

// 나쁜 예: 문자열이 다음으로 넘어감
var story = "옛날 옛날에 어느 마을에 어떤 집에 \
어떤 사람과 어떤 사람이 살았어요.";


// 좋은 예 
var num = 10;
var num = 10.0;
var num = 10.00;
var num = 0xB2;
var num = 3e1;

// 나쁜 예
var num = 10.;  // 소수점 뒤에 숫자 없음
var num = .1;   // 소수점 앞에 숫자 없음
var num = 010;  // 8진수 사용 안함

7. 객체 리터럴

• 여는 중괄호는 중괄호를 여는 문장과 같은 라인에 있어야합니다.
  
• 프로퍼티 - 값 쌍은 여는 중괄호 다음 줄 부터 작성하고 여는 중괄호가 있는 라인을 기준으로 한단계 들여쓰기를 합니다.
• '프로퍼티: 값' 의 형식을 지켜줍니다. 공백없이 콜론을 입력하고 공백 하나 후에 값을 입력합니다.
• 값이 함수라면 프로퍼티명 다음에 한줄로 입력하지 않고 함수 이전 줄, 다음 줄에 공백을 넣어줍니다.
• 관련된 프로퍼티끼리 묶기 위해 프로퍼티간 공백을 넣어도 됩니다.
• 닫는 중괄호는 텍스트와 함께 두지 않으며 끝에 세미콜론(;)을 붙여줍니다.

// 좋은 예
var person = {
    name: "송민재",
    age: 26,
    
    getName: function() {
        return this.name;
    }
};

// 나쁜 예: 함수 이전에 공백이 없음
var person = {
    name: "송민재",
    age: 26,
    getName: function() {
        return this.name;
    }
};

// 나쁜 예: 잘못된 들여쓰기
var person = {
        name: "송민재",
        age: 26,
    
        getName: function() {
            return this.name;
        }
    };

// 나쁜 예
var person = {name: "송민재", age: 26};

 함수에 객체 리터럴을 전달할 때도 간단한 객체는 한 줄로 전달하고 싶겠지만, 가독성을 위해 위의 규칙을 적용해줍니다.

// 좋은 예
getDepartment({
    name: "송민재", 
    age: 26
});

// 나쁜 예: 객체 리터럴 규칙을 지키지 않음
getDepartment({name: "송민재", age: 26});

 객체 프로퍼티 작성 규칙은 8.2 변수명 생성 규칙과 같습니다. 객체 메서드는 9.2 함수명 규칙을 따릅니다. 프로퍼티나 메서드가 private라면 _를 맨 앞에 붙여 private라고 명시적으로 알려줍니다.

var person = {
    _homeAddress: "인천",

    name: "황혁진",
    age: 26,

    _getHomeAdrress: function() {
        return this._homeAddress;
    }
}

8. 변수 선언

8.1 변수 선언 방법

 변수 연산자는 반드시 사용 전에 선언되어야합니다. 한 개의 var을 이용해 함수의 맨 윗줄에 선언하며, 대입 연산자는 같은 단계의 들여쓰기를 사용해주면 가독성에 도움이 됩니다. 마지막 변수 선언 전까지는 ,로 구분을 해주며 마지막 변수에는 세미콜론(;)을 붙여줍니다. 초기화 된 변수는 반드시 초기화 되지 않은 변수보다 앞에 위치 시킵니다.

// 좋은 예
var name    = "권현아",
    age     = 23,
    home    = "방화동";

// 나쁜 예: 대입연산자의 들여쓰기가 맞지 않음
var name = "권현아",
    age = 23,
    home = "서울과 인천의 경계";

// 나쁜 예: 들여쓰기가 맞지 않음
var name    = "권현아",
age     = 23,
home    = "서울과 인천의 경계";

// 나쁜 예: 한 줄에 여러 변수 선언
var name = "권현아", age = 23, home = "서울과 인천의 경계";

// 나쁜 예: 초기화 되지 않은 변수가 먼저 위치함
var name,
    age     = 23,
    home    = "서울과 인천의 경계";

8.2 변수명 규칙

변수명은 낙타표기법을 사용합니다. $나 \는 사용하지 않으며 _도 사용을 자제하겠습니다. 변수명은 소문자로 시작하며 새로운 단어의 첫 번째 문자는 대문자를 사용합니다. 변수명의 첫 단어는 반드시 명사를 사용해주어 함수와 구분하기 쉽도록 합니다. 

// 좋은 예
var firstName = "혁진";

// 나쁜 예: 대문자로 시작
var FirstName = "혁진";

// 나쁜 예: 빈칸 들어감
var first_name = "혁진";

// 나쁜 예: 동사로 시작
var getFirstName = "혁진";

변수를 값이 변하지 않는 상수로 사용하려면 이름의 모든 문자를 대문자로 사용하며 단어 사이에 밑줄( _ )을 넣어줍니다.

var TOTAL_COUNT      = 1,
    TOTAL_POPULATION = 1000;

9. 함수 선언

9.1 함수 선언 방법

• 객체에 선언된 메서드가 아니라면 반드시 함수 선언 형식을 사용합니다.
• 함수 표현식, new를 이용한 생성자 형식을 사용하지 않습니다. (객체 생성 시 사용)
• 함수명과 여는 괄호 '(' 사이에는 공백 넣지 않습니다. '(' 와 ')' 사이에는 공백 하나를 넣습니다.
• 인자 입력시 , 뒤에 공백을 넣습니다.
• 함수 본문은 한 단계 들여쓰기를 사용합니다.

// 좋은 예
function working(arg1, arg2) {
    return money;
}

// 나쁜 예: 함수 명과 괄호 사이에 공백
function working (arg1, arg2) {
    return money;
}

// 나쁜 예: 함수 표현식 사용
var working = function(arg1, arg2) {
    return money;
}

// 나쁜 예: 생성자 방식 사용
var money = new Function("arg1", "arg2");

 익명 함수는 객체에 메서드 할당 시나, 다른 함수에 인자로 전달할 때 사용합니다.

person.name = function() {
    // 코드
};

getName(function() {
    // 코드
});

9.2 함수명 규칙

함수명 역시 낙타표기법을 사용합니다. 첫 번째 단어는 동사를 사용하여 변수명과 구분해줍니다. 

// 좋은 예
function getName() {
    
};

// 나쁜 예: 대문자로 시작
function GetName() {

};

// 나쁜 예: 명사 사용
function name() {

};

// 나쁜 예: _ 사용
function get_name() {

};

 생성자 함수는 new를 통해 생성할 때 실행되는 함수며 객체 인스턴스를 생성할 때 사용하므로 동사로 시작하지 않고, 첫 문자를 대문자로 시작합니다.

// 좋은 예
function Enemy() {

};

// 나쁜 예: 소문자로 시작
function enemy() {

};

10. 문장 규칙

10.1 return문

반환하는 값의 명확한 의미를 알기 위해 괄호를 사용하지 않습니다.

// 좋은 예
var generation = (age <= 7 ? "baby" : "teenager");
return generation;

// 나쁜 예
return (age <= 7 ? "baby" : "teenager");

10.2 if 문

한 문장이라도 중괄호를 포함해줍니다. (다음에 문장을 추가할 때 중괄호를 빼먹는 실수하지 않도록)

// 좋은 예
if (person != null) {
    work();
}

// 나쁜 예
if (person != null)
    work();

10.3 for 문

변수는 for문의 초기화 구문 이전에 선언해줍니다.

// 좋은 예
var i   = 0,
    len = 10;
for (i = 0; i < len; i++) {

}

// 나쁜 예
for (var i = 0; i < 10; i++) {

}

10.4 switch 문

• case는 switch를 기준으로 한단계 들여쓰기 합니다.
• 첫 번째 case를 제외한 case와 default 사이에는 한 줄의 공백이 있어야합니다.
• default를 제외한 case는 return, break, throw 중 하나로 마쳐야 하고 다음 case로 의도적으로 넘기는 부분은 주석처리를 해줍니다.
• default를 의도적으로 생략했으면 주석처리 해줍니다.

// 좋은 예
switch (num) {
    case 0:
        break;
        
    case 1:
        break;
        
    default:
        break;
}

// 좋은 예
switch (num) {
    case 0:
        // 다음 case와 같은 동작 처리

    case 1:
        break;

    default:
        break;
}

// 좋은 예
switch (num) {
    case 0:
        break;

    case 1:
        break;

    // default 구문 생략
}

11. 가독성을 위한 공백

의미 없는 공백은 사용하지 않습니다. 한 줄 공백은 다음의 상황에 사용합니다.

• 메서드 사이
• 메서드와 지역 변수와 첫 번째 문장 사이
• 여러 줄 주석이나 한 줄 주석 이전
• 메서드 내에서 가독성 향상을 위해 논리적으로 나눈 그룹 사이

공백은 다음 상황 때 사용합니다.

• 인자가 여러개 일때 콤마(,) 뒤에 공백을 넣습니다.
• 이항 연산자는 앞 뒤에 공백을 넣고, 단일은 넣지 않는다.
• for 문의 표현식은 공백을 넣어 구분