컨벤션 - 100-hours-a-week/12-marong-Wiki GitHub Wiki

협업 개발 컨벤션

이 문서는 마롱 개발의 코드 품질, 협업, 관리의 일관성을 높이기 위한 Python PEP8 기반의 공통 개발 규칙(컨벤션)을 소개하고 있습니다.

Python 코드 스타일 (PEP8 요약)

1. 인덴트(들여쓰기)

  • 공백 4칸 사용 권장
  • 여러 줄 연결 시, 수직 정렬(아래 예시 참고) 
    foo = long_func(var_one, var_two,
               var_three, var_four)

2. 탭 vs 공백

  • 공백 사용 권장, 탭은 레거시 코드 호환 용도로만 사용 권장
  • Python3: 탭+공백 혼용 금지

3. 최대 줄 길이

  • 코드: 79자
  • 주석/문서 문자열: 72자

4. 연산자 줄바꿈

  • 이항 연산자 앞에서 줄바꿈 권장
# Good (이항 연산자를 앞에 두고 줄바꿈)
total = (first_variable
         + second_variable
         - third_variable)

# Bad (이항 연산자를 뒤에 두고 줄바꿈)
total = (first_variable +
         second_variable -
         third_variable)

5. 빈 줄

  • 최상단 함수/클래스 사이: 2줄 띄우기
  • 클래스 내 메서드 사이: 1줄 띄우기

6. 인코딩

  • Python3: UTF‑8 권장
  • 일반적으로 인코딩 선언 필요 없음

7. 명명 규칙

대상 규칙 예시
모듈/패키지 소문자, 필요시 밑줄
함수/변수 snake_case
클래스 PascalCase(CapWords)
상수 ALL_CAPS_WITH_UNDERSCORES
내부용 _protected (단일 언더스코어)
private __private (이중 언더스코어)
특수 메서드 __magic__ (직접 생성X)
혼동 금지 1, O, l 등 혼동되는 문자 금지

8. 기타

PEP8 요약

  1. 인덴트: 공백 4칸
  2. 최대 길이: 코드 79자, 주석 72자
  3. 명명: snake_case, PascalCase, ALL_CAPS
  4. 빈 줄/줄바꿈: 논리적 구분 명확히
  5. 인코딩: Python3는 UTF‑8
  6. 이름 규칙: 내부용 _, private용 __, 시스템용 __magic__

2. Git 협업 컨벤션

브랜치 전략

  • 메인: main (배포), develop (통합 개발)
  • 기능: feature/기능명
  • 버그fix: fix/이슈명
  • 브랜치명: 소문자, 카멜/스네이크 혼용금지
  • 병합(PR) 전 rebase 권장

커밋 메시지 규칙

feat : 새로운 기능 추가
fix : 버그 수정
docs : 문서 수정
style : 코드 포맷팅, 세미콜론 누락, 코드 변경이 없는 경우
design : 사용자 UI 디자인 변경 (CSS 등)
refactor : 코드 리팩토링
test : 테스트 코드, 리펙토링 테스트 코드 추가
build : 빌드 파일 수정
ci : CI 설정 파일 수정
perf : 성능 개선
chore : 빌드 업무 수정, 패키지 매니저 수정
rename : 파일 혹은 폴더명을 수정만 한 경우
remove : 파일을 삭제만 한 경우
  • 명확한 한글/영어, 구체적으로 작성

커밋 예시

feat: 그룹별 미션 생성 기능 추가(`GroupMissions` Table 연동) #5

fix: LoRA Fine-tuning 파일이 정상적으로 업로드되지 않는 문제 수정

PR(Pull Request) 규칙

  • 제목: prefix + 명확한 설명
  • 내용: 변경 요약/확인사항/관련 이슈 명시
  • 코드리뷰 지정, 셀프체크리스트 활용

폴더/파일 구조

  • 모듈/기능 단위 분리, 공통 폴더(예: config, utils, tests)는 루트에 아래 형식으로 정리
project/
  ├─ app/
  │   ├─ main.py
  │   ├─ module1/
  │   ├─ module2/
  ├─ tests/
  ├─ config/
  ├─ requirements.txt
  └─ README.md

문서화

  • 함수/클래스 docstring
  • 아키텍처, API, 컨벤션 문서 별도 관리(위키/노션 등)
  • README 등 버전별 관리

협업/커뮤니케이션

  • 기본적으로 비동기 커뮤니케이션 기반으로 디스코드 활용
  • 업무/PR 단위 소통, 기록 남기기

참고 링크