프로젝트 작업일지 : 소스 컨벤션

작업일지에 들어가며

이전 프로젝트를 진행하기 전 특강, 멘토링을 들으며 문서화에 대한 중요성을 크게 깨달았다.

 

프로젝트 시작 전 프로젝트 관련 사항들을 문서화하는 것이 굉장히 중요하다고 한다.

 

이전 프로젝트에서는 이 부분이 미흡하다고 생각하였기에 이번 프로젝트는 시작 전 문서화를 꼼꼼히 진행해보려한다.

 

문서화를 꼼꼼히 해두어 프로젝트 진행간의 팀원들과의 마찰을 최대한 줄이고 효율적인 소통을 진행하여

 

커뮤니케이션 코스트를 줄이고자 한다. 우리는 문서화 작업 중 첫 번째로 소스 컨벤션을 정하였다.

---

소스 컨벤션

💡 소스 컨벤션이란?
보통 코드 컨벤션(Code Convention)이나 코딩 컨벤션 (Coding Convention)으로 부르는 모양이다.
내가 작성한 코드를 다른 팀원들도 쉽게 이해할 수 있게 가독성 있는 코드를 작성하는 법에 대한 규칙이다.

Sun에서 소개하는 코딩 컨벤션의 필요성
1. 소프트웨어를 개발하는 일련의 모든 과정에 들어가는 비용 중 80%가 유지보수이다.

2. 소프트웨어의 유지보수를 그 소프트웨어를 직접 개발한 개발자가 담당하는 경우는 드물다.

3. 코딩 컨벤션은 다른 개발자가 그 소스코드를 처음 보았을 때, 더 빠른 시간에 완벽히 이해할 수 있도록
도와주기 때문에, 코드의 가독성이 높아진다.

4. 개발자가 자신의 소스 코드를 제품으로 팔고자 한다면, 자신이 작성한 코드가 다른 소스코드들과 잘 어울리도록
패키지(package)를 적절하게 구성할 필요가 있다.

 

---

소스 컨벤션 작성 과정

하기 내용은 우리 팀의 소스 컨벤션이다.

1. 자바 (Java)

1.1 코드 스타일

• 네이밍 규칙
  • 클래스명 : PascalCase(예: MyClass)
  • 메서드명 : camelCase (예: myMethod)
  • 변수명 : camelCase (예: myVariable)
  • 상수명 : UPPER_SNAKE_CASE (예: MAX_VALUE)
• 들여쓰기
  • 탭 공백 4칸
• 주석
  • 클래스, 메서드, 복잡한 로직에 대한 설명은 Javadoc 형식으로 작성
  • 코드 블록에 대한 설명은 인라인 주석 사용

/**
 * ex. Javadoc 형식
 */

// 인라인 주석

 

1.2 패키지 구조

• 기본 패키지 구조 : com.acorn.project
• 기능별 패키지 구분 : controller, service, repository, ...

2. DB (MySQL)

2.1 데이터베이스 설계

• 네이밍 규칙
  • 테이블명: snake_case, 복수형으로 작성 (예: `members`)
  • 컬럼명: snake_case
    • 테이블명 없이 풀네임으로 작성 (예: no, name, address, … )
    • 외래키 참조 시 ‘테이블명 단수형’_’필드명’ (예: `member_id`)
  • PK : no, 자동증가 설정 (예: `no INT PRIMARY KEY AUTO_INCREMENT`)
  • 불분명한 표현 사용 X (예: `product_B`)
• 인덱스
  • 자주 조회되는 컬럼에 인덱스 추가
  • 외래 키에 인덱스 추가

2.2 SQL 쿼리 작성

• 형식
  • 대문자로 SQL 키워드 작성 (예: SELECT, FROM, WHERE)
  • 쿼리의 각 절은 새로운 줄에 작성

3. Spring Boot

3.1 프로젝트 구조

• 기본 구조 : src/main/java, src/main/resources, src/test/java
• 설정 파일 : application.properties 또는 application.yml 사용

3.2 의존성 관리

• Gradle 사용
• 의존성 추가 시 주석으로 설명 추가

// gradle 주석

# properties.application 주석 (UTF-8 인코딩 설정)

4. Git

4.1 브랜치

• 브랜치 네이밍
  • 기능 개발 : feature/기능명
  • 버그 수정 : fix/버그명
  • 배포 : release/버전명
• 커밋 메시지
  • 형식: 타입 : 간단한 설명
    • 타입 : feat, fix, docs, style, refactor, test, chore
  • 예: feat : 사용자 로그인 기능 추가 test : Test 관련한 코드의 수정, 추가
  • chore : (코드의 수정없이) 설정을 변경
  • feat : 새로운 기능 추가 fix : 기능 수정 style : 스타일 관련 refactor : 코드 리펙토링

4.2 Pull Request (PR)

• PR 제목은 간단명료하게 작성
• PR 설명에 변경 사항 및 리뷰 요청 사항 기재

5. React

5.1 코드 스타일

• 네이밍 규칙
  • 컴포넌트명 : PascalCase (예: MyComponent)
  • props 및 state: camelCase (예: myProp, myState)
• 파일 구조
  • 컴포넌트별 폴더 생성 (예: MyComponent/MyComponent.js, MyComponent/MyComponent.css)

5.2 상태 관리

• React의 상태 관리 라이브러리
• (예: Redux, Context API)

5.3 주석

• 복잡한 로직이나 컴포넌트에 대한 설명은 주석으로 추가
• 코드 블록에 대한 설명은 인라인 주석 사용

/**
 * 복잡한 로직, 컴포넌트 설명은
 * Javadoc과 같은 방식으로 작성
 */
 
// 코드 블록에 대한 설명은 인라인 주석

 

---

작업일지를 마치며

✨ 나의 생각

이전 프로젝트를 진행하며 보완해야만 했던 점으로 바로 이 소스 컨벤션이 안 갖춰져 있다는 것을 생각했다.

시큐리티 기능 개발을 맡으면서 권한에 따른 접근 제한을 걸어주어야 했을 때 팀원들의 요청 URL의 엔드포인트명이 통일되지 못하고 다 달라 기능을 완성하고 테스트해보는데에 있어 원활하지 못했던 기억이 있다.

이번 프로젝트를 진행하며 소스 컨벤션을 미리 맞춰두었기 때문에 아마도 이전과 같은 시행착오를 겪지 않아도 될 것 같다는 생각이 든다. 

---

Reference

🙏 Code Conventions for the Java TM Programming Language

🙏 코드컨벤션(Code Convention) / 코딩 컨벤션 (Coding Convention) 란

🙏 [ Git | git 커밋 컨벤션 설정하기 ]

🙏 캠퍼스 핵데이 Java 코딩 컨벤션