코드 컨벤션 규칙(Code convention rule)[참고용]

필자는 한 번도 코드 컨벤션 문화가 있는 팀에 근무한 경험이 없다는 점을 명확히 알려드립니다. 단순히 업무를 하면서  필요하다고 느낀 부분에서 작성을 하여 공유합니다. 또 현재까지 프로젝트를  하면서 필요하다고 생각한 부분을 규칙을 정하여 지키면서 작업하고 있습니다. 그리고 업무하는 과정에서 계속해서 추가되거나 수정될 것입니다. 컨벤션 규칙은 다음과 같습니다.

---

1. 세로 모니터 환경에서 가독성있게 개발하기 위한 목적

 1) code line tab size와 indent 설정 통일

  ① vue, javascript는 각각 2로 설정 ( 파일첨부 참조: vue_template_indent_set.png )

  ② java는 4로 설정 ( 파일첨부 참조: java_indent_set.png )

 

2. 개발 후 조치

 1) 개발할 때 ESlint를 임시로 적용시키지 않게 주석처리했던 부분은 다시 원복시키고 린트 규칙에 위배되지 않게 수정한다.

 2) console.log, logger.info, System.out.print 등 콘솔에 찍히는 문법은 개발 후 제거한다.

 

3. 네이밍 컨벤션 규칙

 - 팀 전체에서 동일한 명명 규칙을 따르도록 한다. 프로젝트의 일관성은 코드의 가독성과 유지보수성에 큰 영향을 미치기 때문이다.

 - 모든 이름은 의미가 있어야 한다. 약어나 짧은 이름은 피하고, 변수나 메서드의 용도를 명확하게 설명하는 이름을 사용해야한다.

 

 1) 클래스와 인터페이스

  - 파스칼 케이스(PascalCase)로 작성한다. 즉, 각 단어의 첫 글자를 대문자로 쓰고 나머지는 소문자로 작성. [ ex) UserService, CustomerController, DatabaseConnection 등]

 2) 변수

  - 변수의 이름은 소문자로 시작하고, 카멜 케이스(CamelCase)로 작성한다. 변수 이름은 가능한 의미를 가지도록 명확하고 간결하게 작성해야 한다. [ ex) userName, itemPrice, totalCount 등]

 3) 상수

  - 스네이크 케이스(snake_case)로 작성한다. 단 상수의 이름은 모두 대문자로 작성하고 단어 사이를 밑줄(_)로 구분한다. [ ex) MAX_LENGTH, PI_VALUE, DEFAULT_PORT 등 ]

 4) 메서드

  - 메서드의 이름은 소문자로 시작하고, 카멜 케이스(CamelCase)로 작성한다. 그리고 메서드 이름은 동사로 시작한다. 메서드의 목적을 잘 표현해야 하기 때문이다. [ ex) getUserById(), calculateTotal(), openFile() 등]

 5) 패키지

  - 패키지 이름은 모두 소문자로 작성한다. 그리고 도메인 이름을 거꾸로 사용하여 역순으로 작성한다. [ ex) com.example.myproject, org.company.application 등]

 6) 리소스 파일

  - 카멜 케이스(camelCase)로 작성한다. 필요에 따라 단어 사이를 작대기(-)로 구분한다. [ ex) index.html, styles.css, applicationContext-security.properties 등]

 7) 클래스 멤버 접두사

  - 클래스의 멤버 변수 중에서 클래스의 상태를 나타내는 변수에는 보통 is, has, should와 같은 접두사를 사용한다. [ ex) isRunning, hasPermission, shouldUpdate 등]

 8) 예약어 피하기

  - 프로그래밍 언어에서 예약어로 사용되는 단어는 변수나 클래스 이름으로 사용하지 않도록 한다. ( postgresql 예약어 목록 : https://www.postgresql.kr/docs/10/sql-keywords-appendix.html )

 

 9) url 작성 규칙

  - URL 경로는 사용자에게 직관적이고 의미 있는 정보를 제공해야 한다. 사용자가 URL을 보고 해당 페이지의 내용을 유추할 수 있도록 해야 한다.

  - URL 경로는 간결하고 단순하게 구성되어야 한다. 지나치게 복잡한 경로는 사용자에게 혼란을 줄 수 있으며, 검색 엔진에도 해로울 수 있다.

    ( 흔히 빅데이터 솔루션에서 많이 사용하는 ElasticSearch가 도입될 수 있기 때문에 대비한다. )

  - 원칙을 기반으로 URL을 구성하면 사용자와 검색 엔진 모두에게 이해하기 쉬운 웹 애플리케이션을 만들 수 있다.

 

  ① 슬래시 사용: URL 경로의 끝에는 슬래시(/)를 사용하지 않거나 일관성 있게 사용해야 한다. 예를 들어, /products와 /products/는 동일한 페이지를 가리켜야 한다.
  ② 소문자 사용: URL은 대소문자를 구분하므로, 소문자로 통일하여 URL이 구분되지 않도록 해야 한다. 대문자 URL과 소문자 URL이 다른 페이지로 간주될 수 있다.
  ③ 케밥 케이스(kebab-case) 사용: 단어 사이에 공백이 필요한 경우 하이픈(-)을 사용하여 단어를 구분한다. [ ex) /user-profile ]

   - 케밥 케이스 사용은 지양하고 어쩔 수 없는 경우에만 사용. 되도록 '/user/profile' 와 같이 사용하는 것을 권장한다.
  ④ 동사보다는 명사 사용: URL에는 동사보다는 명사를 사용하는 것이 좋습니다. 예를 들어, /create-user보다는 /user/new와 같이 사용한다.
  ⑤ 피해야 할 문자 사용: URL에는 공백, 특수 문자 및 UTF-8 이외의 문자를 피해야 한다. 공백은 %20과 같은 URL 인코딩으로 대체해야 한다.
  ⑥ 유일한 식별자 사용: 단일 리소스를 유일하게 식별하는 데 사용되는 ID 등 유일한 식별자는 경로에 포함시킨다. 예를 들어, /users/123과 같이 사용한다.
  ⑦ 카멜 케이스(camelCase) 사용 금지 : url에 카멜 케이스를 사용하는 것은 사용자로 하여금 가독성이 저하되고 검색 엔진이 URL을 분석 및 해석하는 데 이슈가 발생할 수 있다. 또 대문자가 포함되기 때문에 웹 표준에 맞지 않다.

 

 10) 자료구조에 따른 명칭 정의

  - 반환값의 자료구조가 Map인 경우 구분명사 + "info" 사용 [ ex) url인 경우 /cluster/info 또는 메서드인 경우 getClusterInfo() ]

  - 반환값의 자료구조가 List인 경우 구분명사 + "list" 사용 [ ex) url인 경우 /cluster/list 또는 메서드인 경우 getClusterList() ]