프리코스 컨벤션 통일

이프·2025년 10월 14일
우테코 8기컨벤션

woowacourse

목록 보기
2/7

프리코스는 커밋 컨벤션, 코드 컨벤션 규약이 있습니다!
컨벤션은 꼭 읽고 숙지해야하지만, 매 주 진행되는 미션에서 해당 컨벤션들을 다 기억하고 일일이 적용하기는 힘들다고 생각합니다.

그래서 해당 포스트는 이렇게 반복되는 규칙들을 통일해, 조금이라도 신경을 줄이는 방법을 소개하고자 합니다!

커밋 컨벤션 통일

커밋 컨벤션은 Angular Js Commit Message Convention을 지켜야합니다.
관련된 설명은 해당 링크에서 확인할 수 있지만, 실수나 다른 프로젝트에서의 컨벤션이 습관이 되어 컨벤션을 지키지 못할 수 있습니다.

그래서 커밋 컨벤션을 통일 할 수 있는 Husky를 소개하려고합니다!

  • Husky enhances your commits and more 🐶 woof!
  • Automatically lint your commit messages, code, and run tests upon committing or pushing.

간단히 설명을 하자면, 커밋 전/중/후로 이벤트를 추가할 수 있는 도구입니다.
저는 이 Husky를 활용해 Commit 과정에서 컨벤션이 일치하는지 확인할 예정입니다!

허스키 시작하기

허스키는 여기에서 시작해 볼 수 있습니다.

1. 허스키 설치하기

  • 기본적으로 설치도구가 필요합니다. 저는 Node.js를 선택했습니다.
  • 프로젝트 root에서 npx husky init를 작성합니다.
    • root/.husky 폴더가 설치되었는지 확인하세요!

2. commit-msg 세팅하기

  • .husky 폴더 내부에 commit-msg 파일 생성하기
  • 그리고 커밋 시 동작을 작성하면 됩니다!
#!/usr/bin/env sh
commit_msg_file=$1
commit_msg=$(cat "$commit_msg_file")

pattern="^(feat|fix|docs|style|refactor|test|chore)(\(.+\))?: .{1,}"

if ! echo "$commit_msg" | grep -qE "$pattern"; then
    echo "❌  커밋 메시지 형식 오류"
    echo ""
    echo "✅ 필수 사항: type, subject"
    echo "❎️선택 사항: scope, body, subject"
    echo ""
    echo "===제목 라인==="
    echo "<type>(<scope>): <subject>"
    echo "예시) feat: 로그인 기능 추가, fix(auth): 버그 수정"
    echo "허용 타입) feat, fix, docs, style, refactor, test, chore"
    echo ""
    echo "===본문 라인==="
    echo "<BLANK LINE>"
    echo "<body>"
    echo "<BLANK LINE>"
    echo "<footer>"
    exit 1
fi

저의 경우, 필수 사항만 체크하는 방식으로 했습니다!

3. pre-commit 세팅하기

pre-commit은 커밋전 행동을 작성합니다!

echo "1️⃣커밋 시작"

우선은 간단하게 커밋 시작 메시지만 추가하겠습니다!
뒤에 코드 컨벤션을 통일하면서 pre-commit을 더 추가해보겠습니다.

허스키 확인하기

.husky/
package.json
package-lock.json
node_modules/

커밋을 하기 위해, gitignore에 허스키 관련 작업물 세가지를 추가하고 커밋해보겠습니다!

타입이 없어서, 커밋에 실패한 것을 볼 수 있습니다!
이번에는 타입과 스코프, 본문을 추가해보겠습니다.

성공적으로 커밋이 성공한 것을 확인 할 수 있습니다!
이제부터 커밋 컨벤션에 대한 걱정은 사라졌습니다!! (피로도 -1)

코드 컨벤션 통일

코드 컨벤션은 기본적으로 Java Style Guide를 지켜야합니다.
우테코에서는 추가적인 제약도 있는데요. 추가 컨벤션 링크을 읽어보고 옵시다!

링크에서 확인하면 intelliJ java style XML도 제공하고 있습니다!
혹시나 설정이 다를까봐 직접 확인해봤는데, Google Style에서 추가된 컨벤션 제약에 대해 수정이 잘되어있습니다!

그리고 Style을 적용하는 법은 6기 프리코스 참여자의 블로그에서 확인 할 수 있습니다!
같은 내용을 똑같이 쓰기보다는 추가되는 내용에 집중하겠습니다!

이제 스타일 설정이 완료되었지만, IDE와 다른 참여자의 글을 100% 신뢰 할 수 있나요? 저는 없어서, 조금 더 나은 방식을 찾아보고자 했습니다!
CheckStyle을 활용해서 우리의 코드에 대해 컨벤션이 일치하는지 확인해보도록 합시다!

체크 스타일 적용하기

1. 구글 스타일 다운로드 받기

  • 구글 스타일 링크에서 체크 스타일을 다운로드 받을 수 있습니다.
    • 참고 사항: 해당 링크의 체크 스타일이 최신버전입니다.
  • 구글 컨벤션 베이스이기 때문에, 해당 스타일을 수정하겠습니다.

2. 스타일 수정하기

  • 열제한 변경하기
  <!--1. 열제한 변경 (100 -> 120)-->
  <module name="LineLength">
    <property name="fileExtensions" value="java"/>
    <property name="max" value="120"/>
    <property name="ignorePattern"
             value="^package.*|^import.*|href\s*=\s*&quot;[^&quot;]*&quot;|http://|https://|ftp://"/>
  </module>
  • 들여쓰기 변경하기
    <!--2. 들여쓰기 변경 (기본 2 -> 4, 지속 4 -> 8)-->
    <module name="Indentation">
      <property name="basicOffset" value="4"/>
      <property name="braceAdjustment" value="4"/>
      <property name="caseIndent" value="4"/>
      <property name="throwsIndent" value="8"/>
      <property name="lineWrappingIndentation" value="8"/>
      <property name="arrayInitIndent" value="4"/>
    </module>
  • 수직빈줄 처리하기
    • 수직 빈줄의 경우, 선택사항이라 하지 않아도 됩니다!
    <!--<module name="EmptyLineSeparator">
      <property name="tokens"
               value="PACKAGE_DEF, IMPORT, STATIC_IMPORT, CLASS_DEF, INTERFACE_DEF, ENUM_DEF,
                    STATIC_INIT, INSTANCE_INIT, METHOD_DEF, CTOR_DEF, VARIABLE_DEF, RECORD_DEF,
                    COMPACT_CTOR_DEF"/>
      <property name="allowNoEmptyLineBetweenFields" value="true"/>
    </module>-->

이제 우테코 스타일은 완성되었습니다! 이번에는 체크스타일을 직접 실행해봐야곘죠?

2. 체크스타일 다운로드

체크 스타일은 여기에서 다운로드 받을 수 있습니다.
작성 당시 가장 최신버전으로 12.0.1 버전입니다.

  • jar 다운로드 받기

저는 그림과 같이 ./root/style에 모든 파일들을 다 위치했습니다!
이제 이걸로 끝입니다! 체크 스타일을 한번 확인해볼까요?
(변경된 스타일은 wooteco_checks.xml로 저장했습니다.)

체크 스타일 실행하기

java -jar style/checkstyle-12.0.1-all.jar \
  -c style/wooteco_checks.xml \
  src/main/java

terminal에서 해당 명령을 입력하면 체크 스타일이 실행됩니다!
-c 옵션으로 체크 스타일을 구성 파일로 src/main/java 경로를 검사합니다!

검사 결과 무사히 통과했지만, 보기 불편한 워닝이 발생하네요.
Javadoc 관련한 내용인데 1기 제이가 번역한 가이드 7.3 Javadoc이 어디에 쓰이는지에서 확인해보면, '최소한 Javadoc은 매 public class에 쓰이고 그러한 클래스안에 public, protected 멤버에 쓰인다.' 라고 작성되어있습니다.

즉 필수는 아니라는 말인데 우테코는 가독성 좋은 코드를 권장하기 때문에, 주석의 빈도가 적을 것으로 예상됩니다. 그래서 저는 해당 Warning을 꺼버리겠습니다 :)

워닝제거하기

콘솔에서 확인되는 것처럼 MissingJavadocType, MissingJavadocMethod를 주석 처리 해버릴게요!

<!--<module name="MissingJavadocMethod">
      <property name="scope" value="protected"/>
      <property name="allowMissingPropertyJavadoc" value="true"/>
      <property name="allowedAnnotations" value="Override, Test"/>
      <property name="tokens" value="METHOD_DEF, CTOR_DEF, ANNOTATION_FIELD_DEF,
                                   COMPACT_CTOR_DEF"/>
    </module>-->
<!--<module name="MissingJavadocType">
      <property name="scope" value="protected"/>
      <property name="tokens"
                value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF,
                      RECORD_DEF, ANNOTATION_DEF"/>
      <property name="excludeScope" value="nothing"/>
    </module>-->

결과, 워닝이 제거되고 체크 스타일이 잘 적용된 것을 볼 수 있습니다.
그럼 매 작업마다 checkstyle -> commit 귀찮죠?
우리는 Husky를 사용하므로 자동화해보겠습니다!!

CheckStyle 자동화

1. 에러 레벨 설정하기

이전에 JavaDocType에서 Warning이 뜨지만, 성공하는 것을 볼 수 있었습니다.
이제는 스타일이 맞지 않으면 실패하도록 설정해줍니다!

  <!-- severity warning -> error -->
  <property name="severity" value="${org.checkstyle.google.severity}" default="error"/>

2. 체크스타일 스크립트 생성

#!/bin/bash
# Checkstyle 실행
java -jar style/checkstyle-12.0.1-all.jar \
  -c style/wooteco_checks.xml \
  src/main/java

# 결과 확인
if [ $? -eq 0 ]; then
    echo "✅️ Checkstyle 통과!"
    exit 0
else
    echo "⚠️ Checkstyle 실패!"
    exit 1
fi
  • ./root/checkstyle.sh를 만들어, 위 코드를 작성해줍니다.

3. Pre-Commit 추가

echo "🔍 Checkstyle 검사를 시작합니다..."
chmod +x checkstyle.sh
./checkstyle.sh

4. 확인하기

이번에도 .gitignore에 checkstyle 관련 추적을 제거하고, 테스트를 위해 간단한 코드를 작성한 뒤 테스트 해보겠습니다.

checkstyle.sh
style/
  • gitignore에 추가
public class Main {
	// 맨 위 안비우기
    public static void main(String[] args) {
        // 120줄 초과하기
        String limit = "120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄120줄";
        // 지속 들여쓰기 4칸 하기
        limit.split("줄",
            5);
        // 들여쓰기 2칸 하기
      System.out.println(limit);
    }

}
// 맨 아래 비우기 (아랫 줄에는 줄바꿈 처리 됨)
  • 체크스타일 테스트 코드 작성

예상대로라면, 에러가 3개가 떠야 할 겁니다! 맨 아래 비우고 안비우고는 자유니까요
.

예상한대로, 3개의 실패가 발생했습니다.
그럼 이제 코드를 수정하고 다시 커밋해보겠습니다.

public class Main {
    public static void main(String[] args) {
        // TODO: 프로그램 구현
    }
}

성공적으로 체크스타일 자동화가 완성됐습니다.

마치며

컨벤션을 알아가는 과정부터 컨벤션을 자동화하는 과정까지 진행해봤습니다.
이 과정을 통해 우테코 여러분들께서 코드에만 집중하시고 경쟁력 있는 모습으로, 함께 성장했으면 좋겠습니다 :)

의견이나 피드백, 개선점 등 자유롭게 말씀주시면 감사하겠습니다.

프리코스 진행 과정 중 작성한 글 모음

profile
이프
if (이런 시나리오는 어떨까?) then(테스트로 검증하고 해결) else(다음 시나리오 고민)
이전 포스트

우아한테크코스 8기 시작

다음 포스트

IntelliJ에서 테스트 커버리지 확인하기

0개의 댓글