협업이 쉬워지는 개발 표기법

 

📚 개발 표기법(네이밍 컨벤션) 

1. 표기법(네이밍 컨벤션)이란?

네이밍 컨벤션이란
변수, 함수, 파일, 폴더 등 “이름을 짓는 규칙”입니다.

일관성 있는 네이밍은 협업, 유지보수, 코드 가독성을 높여줍니다.

 

2. 대표적인 표기법 종류와 특징

표기법	예시	주요 사용처
snake_case	get_user_name, user_profile	Python 변수/함수/파일명, Linux 폴더명
camelCase	getUserName, userProfile	JS/Node 변수, 함수, React props
PascalCase	GetUserName, UserProfile	클래스명(React, Java 등)
kebab-case	get-user-name, user-profile	파일명, 폴더명, URL, K8s 리소스명

---

▶️ 간단 설명

• snake_case: 단어를 _로 연결 (주로 Python, Linux)
• camelCase: 첫 단어만 소문자, 이후 단어는 대문자 (JS, React)
• PascalCase: 모든 단어 첫 글자 대문자 (클래스/컴포넌트명)
• kebab-case: 단어를 -로 연결 (파일/폴더/URL/K8s에서 자주 사용)

---

실전 코드 예시

# Python: snake_case (함수), PascalCase (클래스)
def get_user_name():
    pass

class UserProfile:
    pass

// JavaScript: camelCase (함수), PascalCase (클래스)
function getUserName() {}

class UserProfile {}

# Kubernetes: kebab-case
apiVersion: apps/v1
kind: Deployment
metadata:
  name: fastapi-deployment

3. 기술별 표기법 정리 

기술	변수/함수	클래스	파일/폴더명	라우터/리소스명
React	camelCase	PascalCase	kebab-case/camelCase	-
JS/Node	camelCase	PascalCase	kebab-case/camelCase	-
Python	snake_case	PascalCase	snake_case	snake/kebab-case
FastAPI	snake_case	PascalCase	snake_case	kebab-case
Docker	-	-	kebab-case	kebab-case
K8s	-	-	kebab-case	kebab-case

---

📂 예시 폴더 구조

/backend
  /python
    /fastapi
      /app
        user_controller.py
        chat_service.py
        main.py
      requirements.txt
      Dockerfile
      /tests
        test_user_controller.py
        test_chat_service.py
    /flask
      /app
        main.py
        other_routes.py
      requirements.txt
      Dockerfile
      /tests
        test_other_routes.py

  /nodejs
    /controllers
      userController.js
      chatController.js
    /routes
      userRoutes.js
      chatRoutes.js
    /models
      user.js
      chat.js
    /middlewares
      authMiddleware.js
    app.js
    package.json
    .env
    Dockerfile
    /tests
      user.test.js
      chat.test.js

/frontend
  /src
    /components
      ChatBot.jsx
      UserProfile.jsx
    /pages
      MainPage.jsx
      UserPage.jsx
    /utils
      fetchData.js
      useAuth.js
    App.jsx
    index.js
  public/
    index.html
  package.json

/k8s
  fastapi-deployment.yaml
  flask-deployment.yaml
  nodejs-deployment.yaml
  frontend-deployment.yaml
  mongo-deployment.yaml
  mongo-service.yaml
  mysql-deployment.yaml
  mysql-service.yaml

/docker-compose.yml
/.env
/README.md

---

환경변수(.env) 네이밍 컨벤션 & 예시

환경변수란?

• 소스코드에 하드코딩하지 않고, 외부 파일(.env)이나 환경에서 주입하는 설정 값
• 데이터베이스 접속정보, 비밀키, 포트번호 등 민감한 값을 안전하게 관리
• 개발/운영/테스트 환경별로 값만 바꿔주면 배포/테스트 자동화가 가능

네이밍 컨벤션 & 팁

규칙	예시	설명
대문자+언더스코어	MYSQL_HOST, API_PORT	실무에서 가장 많이 쓰는 규칙
서비스명_설정명	REDIS_HOST, JWT_SECRET	여러 서비스 혼용 시 구분 쉬움
환경별 파일 분리	.env.dev, .env.prod	개발/운영 환경 분리 관리

 

💡 .env는 꼭 .gitignore에 추가해서 깃에 올라가지 않게 관리하세요!

# .env 예시

# 공통
NODE_ENV=development

# FastAPI/Flask
API_PORT=8000
SECRET_KEY=your_secret_key

# MySQL
MYSQL_HOST=mysql
MYSQL_PORT=3306
MYSQL_DATABASE=example_db
MYSQL_USER=example_user
MYSQL_PASSWORD=example_pw

# MongoDB
MONGO_HOST=mongodb
MONGO_PORT=27017
MONGO_INITDB_DATABASE=example_mongo
MONGO_INITDB_ROOT_USERNAME=mongo_user
MONGO_INITDB_ROOT_PASSWORD=mongo_pw

# Node.js
JWT_SECRET=your_jwt_secret

# 기타
REDIS_HOST=redis
REDIS_PORT=6379

 

4. 예외 상황 & 실무 주의사항

[실무에서 자주 만나는 예외]

• 외부 패키지/레거시 코드: 네이밍이 달라도 그대로 사용
• 자동 생성 파일: (__init__.py, index.js, Dockerfile) 관례대로 유지
• 상수/환경변수: DATABASE_URL (대문자+언더스코어)
• API 경로/Prefix: /api/v1/... 등 회사마다 다를 수 있음
• 핸들러/이벤트 함수: handleChange, onClickButton 등은 팀 내 관례 따름

---

[팀 컨벤션 정할 때 주의점]

1. 한 프로젝트, 한 규칙
   • 한 프로젝트 내에 파일/폴더 표기법을 반드시 통일하세요.
2. 공식 스타일 가이드 우선
   • Python: PEP8
   • JS/React: Airbnb JS Style Guide
   • K8s: 공식 네이밍 문서
3. 팀 문서로 남기기
   • Notion, Wiki 등 팀 전체가 접근 가능한 곳에 규칙을 명확히 정리
4. 자동화 도구 활용
   • ESLint, Pylint, Prettier 등으로 네이밍 체크 자동화
5. 예외 상황도 문서화
   • 예외적으로 허용하는 케이스, 자동생성 파일 등도 같이 기록
6. 컨벤션 변경 시 팀 합의/전체 리팩토링
   • 변경이 필요한 경우, 반드시 전원 합의 후 일괄 적용

---

5. 팀 컨벤션 문서 예시

# 프로젝트 네이밍 컨벤션 (2025.07.04)

- JS/React 변수/함수: camelCase, 클래스: PascalCase
- Python 변수/함수/파일: snake_case, 클래스: PascalCase
- K8s, Docker 파일/리소스명: kebab-case
- 환경변수/상수: 대문자+언더스코어 (예: DATABASE_URL)
- 예외: Dockerfile, __init__.py, index.js 등 관례대로
- 외부 패키지/자동생성 파일: 원본 유지

---

6. 체크리스트: 프로젝트 시작 전 점검!

1. 폴더/파일명 표기법 한 가지로 통일했나요?
2. 공식 스타일 가이드 확인 후 컨벤션 정했나요?
3. 컨벤션/예외사항 팀 문서로 남겼나요?
4. Prettier, ESLint, Black 등 자동화 도구 적용했나요?
5. DB, API, 서비스별로 폴더/파일 구분이 명확한가요?
6. 환경변수 파일(.env)이 안전하게 관리되고 있나요?
7. 컨벤션/구조 변경 시 팀 전체 합의로 리팩토링하고 있나요?

7. 마무리

• 표기법은 일관성, 협업, 유지보수의 기본
• 공식 스타일 가이드를 바탕으로 팀에 맞는 규칙을 만들고, 예외도 명확히 남기자!