코드 컨벤션과 GitHub 규칙을 정리하면서 느낀 것

배경

혼자 개발할 때는 크게 체감하지 못했는데, 프로젝트를 진행하면서 코드 컨벤션과 GitHub 규칙의 중요성을 확실히 느꼈다.

처음에는 단순히 “코드를 보기 좋게 만드는 규칙” 정도로 생각했는데, 실제로는 그보다 훨씬 중요한 역할을 하고 있었다.

---

코드 컨벤션: 단순한 스타일이 아니다

코드 컨벤션은 단순히 들여쓰기나 네이밍 규칙이 아니다. 팀 전체가 동일한 방식으로 사고하고 코드를 작성하기 위한 약속에 가깝다.

---

왜 필요한가

1. 코드 읽는 속도가 달라진다

컨벤션이 맞춰져 있으면:

• 어디에 어떤 코드가 있을지 예측 가능
• 불필요한 해석 비용 감소

즉,

“이 코드가 왜 이렇게 작성됐지?” → 이런 고민 자체가 줄어든다

---

2. 리뷰 효율이 올라간다

컨벤션이 없으면 리뷰가 이렇게 된다.

• 변수명 지적
• 포맷 지적
• 스타일 논쟁

하지만 컨벤션이 있으면:

👉 리뷰는 로직과 설계에 집중할 수 있다

---

3. 협업 비용 감소

사람마다 스타일이 다르면:

• 코드 일관성 깨짐
• 유지보수 어려움

컨벤션은 결국

“누가 작성해도 비슷하게 보이게 만드는 장치”

---

GitHub 규칙: 협업을 위한 흐름 설계

코드 컨벤션이 “코드 레벨의 규칙”이라면, GitHub 규칙은 작업 흐름(Workflow)을 정의한다.

---

이번에 정리한 규칙들

1. 브랜치 전략

• main → 배포
• develop → 통합 브랜치
• feature/* → 기능 개발

👉 모든 작업은 feature 브랜치에서 시작

---

2. PR 기반 개발

• 직접 merge 금지
• 반드시 PR 생성 후 merge

이 규칙 하나로 얻는 것:

• 코드 리뷰 강제
• 변경 이력 명확
• 실수 방지

---

3. 커밋 단위

이건 생각보다 중요했다.

• 의미 단위로 커밋 분리
• 불필요한 변경 섞지 않기

나쁜 예:

• 기능 + 리팩토링 + 포맷 변경 한 번에

좋은 예:

• 기능 구현
• 리팩토링
• 포맷 수정

👉 각각 분리

---

4. PR 내용 작성

PR을 단순히 “코드 올리는 것”이 아니라 작업을 설명하는 문서로 보기 시작했다.

포함해야 하는 내용:

• 무엇을 했는지
• 왜 했는지
• 어떤 영향이 있는지

---

5. merge 방식

• squash merge 또는 rebase merge 사용
• 커밋 히스토리 깔끔하게 유지

---

느낀 점

처음에는 규칙이 많아질수록 불편하다고 생각했다.

• 브랜치 나누고
• PR 쓰고
• 커밋 나누고

하지만 어느 순간부터 체감이 바뀌었다.

---

규칙이 없을 때

• 코드 찾기 힘듦
• PR 이해하기 어려움
• 커밋 히스토리 혼잡

---

규칙이 있을 때

• 코드 위치 예측 가능
• PR만 봐도 작업 이해 가능
• 문제 발생 시 추적 쉬움

---

결국 느낀 핵심

코드 컨벤션과 GitHub 규칙은

“개발 속도를 늦추는 게 아니라, 전체 개발 효율을 높이기 위한 장치”

---

한 줄 정리

잘 정리된 규칙 하나가, 코드 수백 줄보다 더 큰 가치를 만든다.