프로젝트 컨벤션 설정하기

목표 10월 9일까지 D-day : 95 일
이번 프로젝트 덤덤(가제)에 적용될 컨벤션과 선택한 이유를 정리했습니다.

프로젝트 컨벤션

프로젝트에 컨벤션을 정하는 이유는 코드의 일관성과 가독성을 높여 유지보수와 협업을 원할하게 하고, 개발 규칙을 준수하여 코드 품질을 보장하기 위함입니다.

개인 프로젝트이지만 프로젝트 컨벤션을 정한 이유는 다음과 같습니다.

1. 다른 개발자가 언제든 투입될 수 있는 프로젝트 환경을 구성하는 것을 목표로 하기 때문입니다.
2. 협업 프로젝트를 유지하면서 컨벤션 방식을 학습하면 다른 협업 프로젝트에 더 빠르게 적응할 수 있기 때문입니다.

Java 코딩 컨벤션

한국에서 많이 사용되는 컨벤션(구글,네이버)중에서 네이버 핵데이를 선택했습니다.

• 네이버 핵데이 Java 코딩 컨벤션

네이버 핵데이를 선택한 이유는 다음과 같습니다.

1. 구글 자바 스타일 가이드 기반으로 만들어졌습니다.
2. 컨벤션 정보가 번역본이 아닌 한국어로 작성되어 가독성이 좋습니다.

이러한 이유로 자바 코딩 컨벤션을 빠르게 적응하기 위해서 네이버 핵데이를 선택했습니다.

버전 관리 컨벤션

브런치 전략

제 프로젝트 브런치 전략 선택에 중요한 키워드는 배포 환경 분리,협업 브런치 전략입니다.

1. Git Flow의 장점인 브런치 별로 용도가 명확하여 팀 역할을 나눌 수 있는 환경이 저에게는 맞지 않습니다.
2. GitHub Flow는 단순하고, 빠른 개발이 가능하여 개인 프로젝트에는 적합할 수 있으나,이번 프로젝트의 목표중 하나인 협업 프로젝트로 성장하여 학습하는 목적에는 적합하지 않습니다.
3. GitLab Flow는 테스트 환경이나 라이브 환경을 별도 버전으로 분리할 수 있으며, 협업 브런치로도 학습할 수 있는 브런치 전략이라고 생각했습니다.

개인 프로젝트에서는 일반적으로 기능 개발과 배포를 혼자서 하기 때문에 GitHub Flow가 더 적합할 수 있습니다. 저는 다음과 같은 이유로 GitLab Flow를 선택했습니다.

Template 정리

개인 프로젝트에 Template 컨벤션을 적용하려는 이유를 정리해보았습니다.

1. 효율성 : 효율적인 코드 리뷰가 가능합니다.
2. 학습 목적 : PR을 작성 과정에서 체계적인 문서 작성과 커뮤니케이션 능력을 기를 수 있습니다.
3. PR 문화 흡수: 다른 기업들의 PR 문화 벤치마킹하여 장점을 흡수할 수 있습니다.
4. 책임감 부여 : 코드 변경의 이유와 영향을 고민하게 되어 더 나은 코드 품질을 유지할 수 있습니다.

기타 사항

• 개인 프로젝트에 기업의 PR 문화를 벤치마킹할 때 유지하기 힘든 문화는 간소화를 합니다.

Pull Request 컨벤션

Low Context 커뮤니케이션 문화

질문을 하거나 대답을 할 때, 내가 알고 있는 것을 상대방도 알고 있을 것이라는 것을 가정하지 않고 충분한 문맥을 전달해야 한다는 의무로 작성합니다.

상대방의 의도를 파악하기 위한 추가적인 커뮤니케이션 또는 미스 커뮤니케이션으로 발생되는 비용을 줄이기 위함입니다.

• 작은 규칙: PR은 1,000 Line을 넘을 수 없다.
• PullRequest, Commit의 단위는 최소의 기능 단위로 세분화한다

타이틀 목록 정리

Pull Request 작성시 지켜야할 컨벤션 입니다.

설명에 대한 문구는 서술어가 아니라 명령어로 작성합니다.

타입	설명	예시
기능 추가 (Feature Addition)	feat: [기능 설명]	feat: 사용자 인증 기능 추가
버그 수정 (Bug Fix)	fix: [버그 설명]	fix: 로그인 시 500 오류 수정
문서 업데이트 (Documentation Update)	docs: [문서 설명]	docs: README에 설치 방법 추가
코드 스타일 수정 (Code Style Change)	style: [스타일 설명]	style: 코드 포맷팅 수정
리팩토링 (Refactoring)	refactor: [리팩토링 설명]	refactor: 데이터베이스 접근 로직 개선
성능 개선 (Performance Improvement)	perf: [성능 설명]	perf: 페이지 로딩 속도 개선
테스트 추가 (Add Test)	test: [테스트 설명]	test: 로그인 기능 테스트 추가

GitHub CLI 커맨드 예시

gh pr create --base master --head kms --title "feat: 사용자 인증 기능 추가"

내용 템플릿

## #️⃣연관된 이슈
> ex) #이슈번호, #이슈번호

## 📝작업 내용
> 이번 PR에서 작업한 내용을 간략히 설명해주세요(이미지 첨부 가능)

## :black_nib: 코드 변경 이유
- 변경 사항이 필요한 이유와 프로젝트에 미치는 영향을 설명해주세요.

## 💬리뷰 요구사항(선택)
> 리뷰어가 특별히 봐주었으면 하는 부분이 있다면 작성해주세요
> ex) 메서드 XXX의 이름을 더 잘 짓고 싶은데 혹시 좋은 명칭이 있을까요?

Issue

타이틀 목록 정리

Issue 작성시 지켜야할 컨벤션 입니다.

설명에 대한 문구는 서술어가 아니라 명령어로 작성합니다.

타입	설명	예시
버그 리포트 (Bug Report)	fix: [버그 설명]	bug: 로그인 시 500 오류 발생
기능 요청 (Enhancement Request)	enhancement: [기능 설명]	enhancement: 사용자 프로필 페이지 추가
문서 업데이트 (Documentation Update)	docs: [문서 설명]	docs: README에 설치 방법 추가

GitHub CLI 예시

gh issue create --title "bug: 로그인시 500 오류 발생" 

내용 템플릿

Bug : 버그 리포트 이슈

## 어떤 버그인가요?

> 어떤 버그인지 간결하게 설명해주세요

## 어떤 상황에서 발생한 버그인가요?

> (가능하면) Given-When-Then 형식으로 서술해주세요

## 예상 결과

> 예상했던 정상적인 결과가 어떤 것이었는지 설명해주세요

## 참고할만한 자료(선택)

enhancement: 기능 요청 이슈

## 어떤 기능인가요?

> 추가하려는 기능에 대해 간결하게 설명해주세요

## 작업 상세 내용

- [ ] TODO
- [ ] TODO
- [ ] TODO

## 참고할만한 자료(선택)

Commit message

타이틀 목록 정리

commit 작성시 지켜야할 컨벤션 입니다.

설명에 대한 문구는 서술어가 아니라 명령어로 작성합니다.

타입	설명	예시
feat	새로운 기능 추가	feat: 사용자 인증 기능 추가
fix	버그 수정	fix: 로그인 시 500 오류 수정
docs	문서 수정	docs: README에 설치 방법 추가
style	공백, 세미콜론 등 스타일 수정	style: 코드 포맷팅 수정
refactor	코드 리팩토링	refactor: 데이터베이스 접근 로직 개선
perf	성능 개선	perf: 페이지 로딩 속도 개선
test	테스트 추가	test: 로그인 기능 테스트 추가
chore	빌드 과정 또는 보조 기능(문서 생성기능 등) 수정	chore: 패키지 업데이트

Git CLI

git commit -m "feat: 사용자 인증 기능 추가"

커밋 템플릿

type: subject // 커밋 작업의 내용을 간략히 설명

body (optional) // 길게 설명할 필요가 있을 시 작성
...

footer (optional) // Breaking point가 잇을때나 특정 이슈에 대한 해결 작업일 때

예시 템플릿

perf: 회원 등록 비동기 방식 추가

기존 회원 등록시 동기로 동작하여 약 5초 정도 소요가 되어
외부 api 통신 부분을 비동기로 처리함

Closes #125

문화

이번 프로젝트를 통해 객체지향 프로그래밍을 배우기 위해 객체지향 생활 체조 9가지 원칙 중 3가지를 유지하려고 합니다. 9가지를 모두 유지하면 좋지만, 개발 속도와 객체지향 프로그래밍의 트레이드 오프를 고려하여 3개를 선택했습니다.

제 약점은 불변 객체 사용입니다. 이 약점을 극복하기 위해 불변 객체를 적용하기 좋은 세 가지 원칙을 선택했습니다:

1. 일급 컬렉션을 사용한다:
   • 이유: 컬렉션을 포함하는 클래스를 사용하여 컬렉션을 일급 객체로 다루면 불변성을 유지하기 쉬워집니다. 컬렉션에 직접 접근하는 대신 컬렉션을 관리하는 클래스를 통해 접근하게 되어, 컬렉션의 상태 변화를 제어하고 관리하기 용이합니다.
   • 효과: 컬렉션의 일관성을 유지하고, 비즈니스 로직을 캡슐화하여 코드의 응집도와 가독성을 높입니다.
2. 2개 이상의 인스턴스 변수를 가진 클래스를 쓰지 않는다:
   • 이유: 인스턴스 변수가 많아질수록 클래스의 상태를 관리하기 어려워지고, 불변성을 유지하기 힘들어집니다. 인스턴스 변수를 3개 이하로 제한하면 클래스가 단순해지고, 상태 변경을 최소화할 수 있습니다.
   • 효과: 클래스의 복잡성을 줄이고, 불변 객체를 작성하기 용이하게 합니다. 작은 단위의 클래스를 만들어 응집도와 재사용성을 높입니다.
3. getter/setter/프로퍼티를 쓰지 않는다:
   • 이유: getter와 setter를 사용하면 객체의 내부 상태를 외부에서 쉽게 변경할 수 있어 불변성을 유지하기 어렵습니다. 대신, 필요한 데이터를 생성자나 메서드를 통해 제공하고, 객체의 상태를 변경하지 않도록 합니다.
   • 효과: 객체의 불변성을 유지하여 코드의 안전성과 안정성을 높입니다. 객체의 상태를 변경하지 않고 필요한 데이터를 제공함으로써, 객체의 책임을 명확히 하고 코드의 응집도를 높입니다.

수정 사항

• 24/07/07 :
  1. issue enhancement 템플릿 제거
  2. pr template 구현 세부사항, 앞으로의 과제, 참고 자료 항목 제거
  3. 리뷰 요구사항 추가

참조

• 뱅크 샐러드 개발 문화