협업을 위한 코드 작성법
같이 코딩할 때 덜 싸우는 법: 협업을 위한 코드 작성 습관들
이번 파트는 사실 “코딩 실력”보다 “같이 일하는 능력”에 더 가까워요.
왜냐면… 솔직히 말하면 같은 기능을 만들어도, 코드를 읽기 쉽게 써 둔 사람이 결국 이깁니다. (내가 나중에 봐도 그렇고요. 어? 이거 내가 쓴 건데 왜 이렇게 헷갈리지… 같은 느낌!)
이전 글에서 작은 프로젝트를 확장해봤다면, 이제는 확장하면서 생기는 혼돈을 정리하는 방법을 잡아볼게요. 주제는 7-4. 협업을 위한 코드 작성법입니다.
협업에서 제일 먼저 터지는 문제: “이 코드 뭐야?”
내가 예전에 팀 프로젝트 하다가 진짜 웃픈 일이 있었거든요.
내가 만든 기능인데도 누가 “이 부분 왜 이렇게 짜셨어요?”라고 물어보더라고요.
나는 그때 이렇게 대답했죠.
“어… 그냥 그렇게 하면 빨라질 것 같아서요.”
…네, 그 대답은 진짜 도움이 안 됐습니다. 솔직히 아직도 그날 얼굴이 기억나요. 음...
그래서 오늘은 아래 3가지를 잡을 거예요.
- 주석: 왜/무엇을 하는지 남기기
- 네이밍: 변수/함수 이름으로 설명하기
- 버전 관리: 실수했을 때 되돌아갈 수 있게 하기
1) 주석은 “설명서”처럼, 하지만 남발은 금지
주석은 대단한 문장이 아니라, 미래의 내가 이해하도록 돕는 힌트라고 생각하면 돼요.
✅ 좋은 주석 예시
- “왜 이렇게 했는지”
- “이 코드가 처리하는 규칙”
- “주의해야 하는 부분”
예를 들면 이런 느낌:
# 유효성 검사: 공백만 들어오면 입력으로 처리하지 않는다
if input_text.strip() == "":
return "빈 입력은 불가"
이건 “무엇을 하는지”가 코드 자체로도 보이니까, 주석이 힘을 보태는 형태예요.
❌ 안 좋은 주석 예시
- 코드 한 줄 한 줄을 그대로 복사해서 주석으로 적는 경우
- 주석이 코드랑 불일치하는 경우
예를 들어:
# i를 1씩 증가
i = i + 1
이건… 솔직히 말하면 필요가 없어요. 코드가 이미 말해주거든요.
결론: 주석은 코드를 다시 읽게 만드는 이유를 남기는 용도면 딱 좋아요.
2) 네이밍은 “내가 대신 말해주는 기능”
여기서 진짜 중요한 포인트.
코드에서 가장 먼저 읽히는 건 문법이 아니라 이름이에요.
x,tmp,data1
이런 건 초반엔 편한데, 협업에서는 거의 “아무 말 안 하는 사람”이 됩니다.
✅ 네이밍은 이런 기준으로
- 변수/함수 이름은 무슨 역할인지 드러내기
- 약어는 팀에서 합의가 없으면 줄이기
- 범위를 좁히고, 정확하게 부르기
예를 들어서:
# ❌ 뭐가 들어오는지 모름
temp = 0
# ✅ 의도가 드러남
total_score = 0
또 함수도 그래요.
# ❌ 의미 불명
def doStuff():
pass
# ✅ 역할이 보임
def calculate_total_score():
pass
이름이 좋아지면, 나중에 누가 읽어도 “아! 이게 그거네”가 바로 나와요.
진짜로요. 내가 예전에 네이밍만 정리하고도 유지보수 시간이 확 줄었던 경험 있어요. (그땐… 내가 천재인 줄 알았지. 사실은 습관이었음)
3) 버전 관리는 “실수 보험”
협업에서 버전 관리는 그냥 도구 이야기가 아니라, 심리 안정에 가까워요.
왜냐면 누군가 실수로 이상한 걸 올려도
- 되돌릴 수 있고
- 바뀐 내용을 확인할 수 있고
- 누가 언제 뭘 했는지 남기니까요.
✅ 커밋 메시지(로그) 작성 팁
커밋 메시지는 길게 쓸 필요 없어요. 대신 명확하게.
좋은 커밋 느낌:
fix: 로그인 예외 처리 추가feat: 메뉴 출력 UI 개선refactor: 변수명 정리 및 중복 함수 제거
이런 식이면, 팀이 코드를 보기 전에 “아 지금 무슨 일이 있었지?”를 파악할 수 있어요.
그리고 중요한 거 하나:
- 커밋은 “크게 한 방”보다 작게 자주
→ 중간에 뭔가 망가져도 원인 찾기가 쉬워져요.
나름 꿀팁인데, 내가 예전에 한 번에 커밋했다가 “어느 줄에서 망했지?”로 밤을 새운 적이 있어요. 유머가 아니라 진짜로. 그래서 지금은 커밋을 쪼갭니다.
4) 팀 코드 스타일은 “협약”이 있어야 편해져요
협업에서 은근히 많이 싸우는 게 이거예요.
- 들여쓰기 2칸?
- 함수는 어디에 배치?
- 예외 처리는 어떤 패턴?
사실 기술보다 규칙이 먼저 정리되면 편해요.
내가 추천하는 방식
- 시작 전에 간단한 스타일 규칙을 정하기
- 가능하면 자동 포맷터/린터를 쓰기
(코드가 알아서 정돈되니까 “취향 싸움”이 줄어요.)
이전 글에서 프로젝트를 확장하면서 “코드가 늘면 관리가 중요해진다”를 느꼈을 거예요.
협업은 그걸 더 빨리, 더 강하게 겪습니다. 그래서 규칙이 필요해요.
5) 협업을 위한 “코드 작성 체크리스트”
포스팅을 마무리하기 전에, 내가 실제로 프로젝트 시작할 때 자주 보는 체크리스트를 줄게요.
- [ ] 변수/함수 이름이 역할을 설명하나?
- [ ] 주석은 “왜”와 “주의” 위주로 달려 있나?
- [ ] 로직이 길어지면 함수로 분리했나?
- [ ] 커밋이 너무 크게 뭉쳐 있지 않나?
- [ ] 누가 봐도 예상 흐름이 이해되나?
이거만 챙겨도 코드가 갑자기 “사람 사는 코드”가 됩니다. 음… 진짜로.
다음 글(7-5)로 자연스럽게 이어가기
솔직히 말하면, 협업 습관(주석/네이밍/버전 관리)은 시작점이에요.
그리고 다음 단계에서는 “그걸 바탕으로 어디까지 더 발전할지”가 중요해져요.
그래서 다음 글 7-5에서는 다음 단계로 나아가기를 주제로,
- 더 좋은 구조로 성장하는 방법
- 스스로 프로젝트를 확장해가는 방향
- 그리고 “내가 어느 정도 수준인지” 점검하는 기준
이런 내용으로 이어갈게요.
원하면, 너희가 하고 있는 언어(예: Python / JavaScript / Java)랑 팀 규모(혼자? 2~3명? 5명 이상?) 알려줘.
그 상황에 맞춰서 주석/네이밍/커밋 예시를 더 딱 맞게 만들어줄게!
