코딩 컨벤션 문서 찾기

Chapter 7. 코드베이스 적응

"코드를 어떻게 써야 하지?"

프로젝트 구조를 파악했다. 개발 환경도 세팅했다. 이제 첫 작업을 받았다.

"간단한 API 하나 만들어봐. 사용자 목록 조회하는 걸로"

자리에 앉았다. 코드 에디터를 켰다. 손가락이 키보드 위에 올라갔다. 그런데?

'함수 이름을 어떻게 지어야 하지? getUserList? get_user_list? GetUserList?'

'들여쓰기는 스페이스? 탭? 2칸? 4칸?'

'중괄호는 같은 줄? 다음 줄?'

옆자리 코드를 슬쩍 봤다. camelCase를 쓰고 있다. 다른 파일을 열어봤다. snake_case를 쓰고 있다.

'어느 게 맞는 거지?' 걱정하지 마라. 모든 회사에는 코딩 컨벤션이 있다. 여기서는 그 컨벤션을 어디서 찾고, 어떻게 따라야 하는지 정리했다.

코딩 컨벤션이 뭔가요?

코딩 컨벤션(Coding Convention)이란 팀에서 약속한 코드 작성 규칙이다.

변수 이름은 어떻게 짓는지, 들여쓰기는 몇 칸인지, 함수는 어떻게 나누는지. 이런 것들을 코드를 통일한다.

왜 필요할까?

혼자 개발하면 내 스타일대로 쓰면 된다. 하지만 회사는 다르다. 여러 사람이 같은 코드를 본다.

만약 A 개발자는 camelCase, B 개발자는 snake_case를 쓴다면? 코드가 뒤죽박죽이다. 읽기 어렵다.

컨벤션이 있으면 누가 쓴 코드든 비슷하게 보인다. 읽기 쉽다. 유지보수하기 쉽다.

컨벤션 문서는 어디 있나?

1. 사내 위키 확인

Confluence, Notion, Google Docs 같은 곳에 보통 있다.

"개발 가이드", "코딩 스타일 가이드", "코드 작성 규칙" 이런 제목으로 검색하면 나온다.

입사 첫 주에 인사팀이나 팀장이 위키 링크를 보내주는 경우가 많다. 메일함도 검색해보자.

2. 프로젝트 README 확인

README 파일에 컨벤션 링크가 있는 경우도 많다. 해당 링크를 따라 컨벤션 사이트에 접속해보자.

3. CONTRIBUTING.md 파일

오픈소스 프로젝트나 잘 정리된 프로젝트에는 CONTRIBUTING.md 파일이 있다.

여기에 코드 작성 방법, PR 올리는 방법, 커밋 메시지 규칙 등이 나와 있다.

4. 린터/포매터 설정 파일

문서가 없어도 괜찮다. 설정 파일만 있으면 자동으로 따를 수 있다.

.eslintrc .prettierrc, .editorconfig 파일을 확인해보자.

5. 동료에게 물어보기

"코딩 컨벤션 문서 어디 있어요?" 이 질문 하나면 된다.

처음 코드 컨벤션 지적사항을 받은날이 아직도 기억난다.

"함수명은 camelCase로 작성해주세요." "들여쓰기는 스페이스 2칸입니다." "문자열은 작은따옴표를 사용해주세요." 스타일 지적이라니? 당황스러웠다. 당황한 나에게 선배는 조심스럽게 말해주었다. "로직은 괜찮아요. 근데 스타일이 좀 다르네요. 우리 컨벤션 문서 못 봤어요?"

"컨벤션 문서요?"

"아, 아무도 안 알려줬구나. 여기 있어요." 링크를 받았다. Notion 문서였다.

아, 코드를 잘 짜는 범위 안에는 코딩 컨벤션 규칙을 잘 지키는 것도 포함된다는 걸 이제서야 알게 된 것이다.

네이밍 규칙

camelCase (카멜케이스)

첫 단어는 소문자, 그다음 단어부터 대문자로 한다. 마치 글자 모양이 낙타 등처럼 생겨서 카멜 케이스다.

예시 : 'getUserList firstName',' calculateTotalPrice'

주로 사용: JavaScript, Java, TypeScript

snake_case (스네이크케이스)

모든 단어를 소문자로, 단어 사이를 언더스코어로 마치 뱀이 기어가는 모습같다. (나만 그렇게 생각하나?)

예시 : 'get_user_list first_name','calculate_total_price'

주로 사용: Python, Ruby, PHP

PascalCase (파스칼케이스)

모든 단어를 대문자로 시작하는 방식이다. 단순하지만 개인적으로 눈에 잘보이는 방식이다.

예시 : GetUserList UserService CalculateTotalPrice

주로 사용: 클래스명 (Java, C#, TypeScript)

kebab-case (케밥케이스)

모든 단어를 소문자로, 단어 사이를 하이픈으로 한다. 개인적으로 눈에 잘안들어오는 규칙이다.

예시 : user-profile main-content button-primary

주로 사용: CSS 클래스명, URL

실전팁

어떤 회사는 JavaScript에서도 snake_case를 쓴다. 어떤 회사는 혼용한다.

정답은 없다. 팀의 규칙을 따르면 된다. 기존 코드가 메뉴얼이다. 열어서 패턴을 보자. 대부분 비슷한 스타일로 되어 있다. 그대로 따라 하면 된다.

들여쓰기, 줄바꿈, 한 줄 최대 길이 규칙

코드를 어떻게 정렬할 것인가. 사소해 보이지만 실제로는 꽤 중요한 문제다. 들여쓰기가와 줄바꿈 규칙이 없으면 코드를 읽기 힘들다.

여기 몇 가지 대표적인 예시를 보자.

들여쓰기 스페이스 2칸

function hello() {

console.log('hello');

}

들여쓰기 스페이스 4칸

def hello():

print('hello')

들여쓰기 탭

func hello() {

fmt.Println("hello")

}

회사마다, 언어마다 다르지만 보통 Python은 보통 4칸, JavaScript는 2칸이 정석이다.

줄바꿈

중괄호는 같은 줄? 다음 줄?

// K&R 스타일 (같은 줄)

function hello() {

console.log('hello');

}

//Allman 스타일 (다음 줄)

function hello()

{

console.log('hello');

}

JavaScript는 보통 줄K&R 스타일로 C#은 보통 줄에 Allman 스타일로 한다. 개인적으로 Allman 스타일이 좋다. 뭔가 보기가 더 시원하다 다만 엔터 값이 너무 많아 스크롤이 길어지는 단점이 있다.

한 줄 최대 길이

모니터 가로까지 얼마나 길게 쓸 수 있는지 규칙으로 정하기도 한다. 보통 80자 또는 120자이다. 요즘은 모니터가 커져서 120자까지 혹은 무제한으로 허용하는 회사도 많다.

예전에 가로 길이를 80자 제한이 있는 프로젝트에서 일한 적이 있다. 처음엔 답답했다. 변수명 좀 길게 쓰면 바로 줄바꿈해야 했다. 근데 한 달쯤 지나니까 오히려 편했다. 코드 리뷰할 때 가로 스크롤 할 필요가 없었고 그닥 크지 않은 모니터 화면에서도 잘 보였던 기억이 난다. 그런데 다시 80자 제한을 건다면 거절할거 같다.

린터와 포매터

수동으로 컨벤션을 지키려면 손이 많이 간다. 그래서 회사에서는 자동화 도구를 많이 사용한다.

린터 (Linter)

코드의 문제점을 찾아주는 도구다. 들여쓰기가 잘못됐거나, 사용하지 않는 변수가 있거나, 세미콜론을 빼먹었을 때 "여기 문제 있어요" 하고 알려준다. JavaScript라면 ESLint, Python이라면 Pylint, Java라면 Checkstyle을 주로 쓴다. 설정 파일에 규칙을 정의해두면, 코드를 작성할 때마다 실시간으로 체크해준다. IDE에서 빨간 줄로 표시된다.

포매터 (Formatter)

코드를 자동으로 정리해주는 도구다. 들여쓰기, 줄바꿈, 따옴표, 세미콜론 같은 것들을 규칙에 맞게 자동으로 바꿔준다. JavaScript는 Prettier, Python은 Black, Java는 Google Java Format을 많이 쓴다.

특히 Prettier는 "저장하면 자동으로 정리"된다. 내가 아무렇게나 쓰고 저장만 하면, 알아서 들여쓰기 맞춰주고 따옴표 통일해준다. Black은 "타협 없는 포매터"라고 스스로를 소개한다. 설정도 필요 없다. 그냥 실행하면 끝.

IDE 설정

VSCode, IntelliJ 같은 IDE에서 포매터를 설정하면, 저장할 때마다 자동으로 정리된다. 린터와 포매터를 함께 쓰면 더 강력하다. 린터가 문제를 잡아주고, 포매터가 스타일을 맞춰준다.

컨벤션 문서가 없다면?

작은 스타트업이나 레거시 프로젝트는 문서가 없는 경우가 흔하다. 그리고 작은 규모의 회사들도 컨벤션 문서가 없는 경우가 많으니 당황하지 말자.

기존 코드를 따라 하라

제일 최근에 작성된 코드 3~5개를 열어보자.

패턴이 보인다. 다들 비슷하게 쓰고 있다. 그대로 따라 하면 된다.

린터 설정 파일을 보라

.eslintrc, .prettierrc 같은 파일이 있으면 그게 컨벤션이다.

IDE에서 자동으로 적용되게 설정하면 된다.

물어보라

"우리 팀 코딩 스타일이 어떻게 되나요?" 이 질문 하나면 된다. 선배가 알려줄 것이다.

직접 만들 수도 있다

입사하고 한 6개월쯤 지나면 "우리 팀 컨벤션 정리하면 어떨까요?" 제안해본 건 어떨까?

기존 코드를 분석해서 문서로 만들면 된다. 팀원들이 고마워할 것이다.

체크리스트: 코딩 컨벤션 파악 완료

컨벤션 문서

사내 위키에서 코딩 가이드 찾기

README나 CONTRIBUTING.md 확인

동료에게 컨벤션 위치 물어보기

네이밍 규칙

변수명 스타일 파악 (camelCase? snake_case?)

함수명 스타일 파악

클래스명 스타일 파악

들여쓰기

스페이스인가 탭인가?

몇 칸인가? (2칸? 4칸?)

중괄호는 같은 줄? 다음 줄?

린터/포매터

프로젝트에 린터 있는가? (.eslintrc 등)

포매터 있는가? (.prettierrc 등)

IDE에 자동 포맷 설정했는가?

컨벤션은 규칙이 아니라 약속이다

필자는 처음엔 컨벤션이 귀찮게 느껴진다. 지금 이 글을 읽는 여러분도 아마 비슷한 생각을 할 수 도 있다.

'camelCase든 snake_case든 무슨 차이야. 작동만 하면 되는 거 아닌가?' 맞다. 작동은 한다.

하지만 코드는 혼자 개발하는 게 아니고 집단의 지성으로 만들어간다. 내 코드를 다른 사람이 읽는다. 다른 사람 코드를 내가 읽는다. 그때 스타일이 통일되어 있으면 훨씬 읽기 쉽다.

컨벤션은 규칙이 아니라 약속이다. 팀원들과의 약속이다. 처음 몇 주는 익숙하지 않아서 실수한다. 괜찮다. PR에서 지적받으면 고치면 된다. 한 달쯤 지나면 손에 익는다. 그다음엔 자연스럽게 컨벤션대로 쓰게 된다.

컨벤션을 파악했다면, 이제 실제 코드를 쓸 준비가 된 것이다.