개발자끼리 통하는 폴더 이름 짓기, 어렵지 않아요
예전에 내가 만든 프로젝트인데, 딱 열자마자 '이게 뭐였더라…' 하고 멍했던 적 있죠? 아니면 다른 사람이 넘겨준 코드인데, 구조가 너무 뒤죽박죽이라 몇 시간은 구조 파악만 하게 되는 경우도요. 진짜 흔한 일이에요. 근데 꼭 그래야 할 필요는 없더라고요.
여기서 소개하는 방법은 딱딱한 규칙이라기보다는, 코드 짜는 우리들끼리 약속 같은 거예요. 조금만 정리해두면 협업도 훨씬 편하고, 나중에 내가 다시 봐도 감 잡기 쉽거든요.
폴더 이름에도 '성격'이 담긴다니까요?
- 이름만 봐도 '아, 이 폴더는 이런 거구나' 하고 느낌이 와야 해요.
- 그래야 다른 사람이 들어와도 헷갈리지 않고 금방 적응할 수 있어요.
저는 개인적으로 폴더 구조가 그 앱의 소개글처럼 느껴져야 한다고 생각해요. 이름만 봐도 '이게 어떤 기능 하는지'가 대충 보여야 진짜 잘 만든 구조죠. 그런 구조는 함께 일할 때도, 나중에 유지보수할 때도 시간 아낄 수 있어요.
완벽한 방법은 없지만, 이건 꽤 괜찮아요
- 폴더를 어떻게 나눌지는 사람마다 다르지만, 기준 하나만 있어도 체계적으로 정리할 수 있어요.
- 언어나 프레임워크가 달라도, 기본 원칙은 유지할 수 있습니다.
저도 예전엔 구조 잡는 데 시간 낭비 많이 했어요. 지금 이 방법은 '적당히 정리하면서도 복잡하지 않은 방식'이라 참 마음이 편해요. 꼭 이대로 하라는 건 아니고, 본인 스타일에 맞게 살짝 바꿔도 전혀 문제 없어요.
이름 지을 때 너무 깊게 고민하지 마세요
- 폴더 이름은 간단하고 눈에 익는 단어가 좋아요.
- 파이썬 쓴다면 소문자 이름이 기본이에요.
- 조금 더 범용적인 이름이면 나중에 확장할 때 유리해요.
예를 들어, 사용자 등록 시스템 만든다고 치면 그냥 user 폴더 하나 만들면 딱이에요. 굳이 user_registration처럼 길게 쓰면 나중에 기능 추가할 때 불편해질 수 있어요. 예전에 'user_auth', 'user_profile' 이런 식으로 폴더 나눴다가 헷갈려서 싹 다시 정리한 기억이 아직도 생생해요.
src 폴더, 진짜 신세계였어요
- 진짜 핵심 코드만 src 폴더 안에 깔끔하게 넣으세요.
- 문서나 테스트 코드는 src 바깥에 둬야 헷갈리지 않아요.
- 이런 분리 덕분에 나중에 코드를 볼 때 훨씬 빠르게 파악돼요.
처음엔 src 폴더가 왜 필요한가 싶었는데, 써보니 완전 꿀이에요. 앱 폴더 안에 src 딱 만들어두고 나면 뭔가 되게 정돈된 느낌이 들어요. 이 안에 각종 폴더 정리해두면 코드 관리가 진짜 수월해요.
1. user_controllers
사용자가 앱에서 어떤 행동을 했을 때, 앱이 어떻게 반응할지를 정해주는 코드가 여기에 있어요.
- 이름 규칙: 앱 이름 + controllers
- 예시: user_controllers
2. user_models
데이터 구조나 사용자 정보 같은 걸 정의한 코드가 이 폴더에 들어가요.
- 이름 규칙: 앱 이름 + models
- 예시: user_models
3. user_views
사용자가 실제로 보게 되는 화면 관련 파일들 (HTML 같은 거) 여기에 있어요.
- 이름 규칙: 앱 이름 + views
- 예시: user_views
4. user_services
컨트롤러도 아니고 모델도 아니고… 그 사이 어디쯤에 있는 핵심 로직들? 그런 것들은 여기에 담으면 딱이에요.
- 이름 규칙: 앱 이름 + services
- 예시: user_services
공통 코드? utilities로 모으면 깔끔해요
- 여러 앱에서 공통으로 쓰는 함수나 유틸성 코드는 utilities 폴더에 넣으세요.
- 이 폴더는 앱 안이 아니라, 프로젝트 맨 위에 두는 게 좋아요.
예전에 유틸 함수들을 각각 앱 폴더 안에 따로 두다가, 결국 겹치는 거 한가득 생기고 중복 코드만 늘어났어요. 그래서 utilities 폴더 하나 만들어서 위에 올려놨더니 얼마나 정리되던지요.
상황에 따라 폴더 더 만들면 돼요
- 이메일 기능 있으면 user_emails 폴더 만들어도 돼요.
- 이름 규칙만 지키면 구조 확장은 문제 없어요.
기능이 많아지면 자연스럽게 폴더도 늘어나죠. 예를 들면, 사용자에게 메일 보내는 기능이 있다면 user_emails 폴더 하나 파는 거예요. 저도 프로젝트 중에 로그 저장하는 기능 추가하다가 user_logs 폴더 만들어서 썼는데, 그때부터 로깅 구조가 정리되더라고요.
프론트엔드랑 백엔드는 확실히 분리해야죠
웹 개발할 때 프론트엔드랑 백엔드가 한데 섞이면 진짜 혼란 그 자체에요. 보안도 문제고요. 그래서 저는 frontend 폴더를 프로젝트 루트에 따로 두고, 앱 이름으로 나눠둬요.
- frontend/user
- frontend/forum
이렇게 하면 코드 짤 때도 헷갈리지 않고, 나중에 디버깅할 때도 훨씬 편해요.
설정 파일은 딱 하나, settings.py
- API 키나 환경 설정은 한 곳에 몰아서 관리하면 속 편해요.
- 앱이 여러 개 있어도, 하나의 설정 파일로 정리하는 게 훨씬 낫습니다.
저는 초기에 앱마다 설정 파일 따로 뒀다가 나중에 환경 바꿀 때마다 진땀 뺐어요. 결국 settings.py 하나로 통일했는데, 진작 이렇게 할 걸 싶더라고요.
예시: 앱이 여러 개인 프로젝트 구조
- 앱이 여러 개 있어도 각자 자기 공간을 가지게 해야 깔끔해요.
- 공통된 요소는 프로젝트 최상단에 두면 관리가 쉬워져요.
예전에 커뮤니티 플랫폼 하나 만들었을 때 user 앱이랑 forum 앱 따로 있었어요. 그때 아래 구조처럼 정리해뒀더니, 나중에 팀원들한테 설명할 때도 한결 수월했어요.
community_center_project/
│
├── settings.py
├── utilities/
├── frontend/
│ ├── user/
│ └── forum/
├── src/
│ ├── user/
│ │ ├── user_controllers/
│ │ ├── user_models/
│ │ ├── user_views/
│ │ └── user_services/
│ └── forum/
│ ├── forum_controllers/
│ ├── forum_models/
│ ├── forum_views/
│ └── forum_services/
마무리하면서 — 내일의 나를 위한 배려
- 코드 구조가 깔끔하면, 미래의 나나 동료도 웃게 됩니다.
- 정리된 폴더 하나가 협업의 질을 높여줘요.
정리해보면, 이 구조는 그냥 보기 좋아서가 아니라 진짜 실용적이에요. 유지보수 편하고, 재활용도 쉽고, 무엇보다 미래의 나를 배려하는 방식이죠. 협업할 때도 팀원들이 정말 고마워할 거예요.
이제 파일 이름 지어볼까요?
- 폴더 구조 만들었으면, 이제 파일 이름도 깔끔하게 가야죠.
- 컨트롤러, 모델, 뷰 같은 내부 파일 이름도 정하는 방법 알려드릴게요.
이제 폴더 구조는 어느 정도 정리됐으니, 다음은 폴더 안에 들어갈 파일들! 그 파일들을 어떤 기준으로 이름 붙이면 좋은지, 다음 편에서 이어가 볼게요.
결국 누가 읽든, 이해하기 쉬운 코드가 최고 아닐까요?
'SW > Coding' 카테고리의 다른 글
| 초보 개발자를 위한 회원가입 컨트롤러 구조 설계 방법 (0) | 2025.05.29 |
|---|---|
| MVC 패턴 속 숨은 핵심, 컨트롤러 제대로 이해하기 위한 쉬운 예시 모음 (0) | 2025.05.28 |
| 개발 전에 꼭 알아야 할 유즈케이스 작성법, 이렇게 쉽다고요? (0) | 2025.05.25 |
| 앱 기획 초보자를 위한 와이어프레임 그리기 실전 가이드 (0) | 2025.05.24 |
| 혼자 개발할 때 꼭 필요한 화면 구조도와 와이어프레임 설계 가이드 (0) | 2025.05.23 |