조직에서 개발한 어플리케이션은 시간이 지날수록 숨 쉬듯이 많은 변화가 발생한다. 이 과정에서 개발자들의 코드 작성 스타일들이 반영되는데 규칙없이 개발된다면 기존 코드의 유지보수가 불가능한 상황까지 오게 될 것이다. 최악의 경우 새로 만들어야 할 경우가 발생할 것이며 비용은 추가로 들게 될 것이다.

오래전부터 이러한 위험을 최소화 하고자 코드 규칙(Coding Convention)을 정하고 문서화하여 사용했지만 약속을 하는 것이기 때문에 지키지 않으면 의미가 없게 된다. 최근에는 코딩 스타일 및 규칙을 설정한대로 “자동화” 하여 강제로 적용하는 오픈소스 도구들을 많은 곳에서 사용하고 있으며, 아래와 같은 2가지 형태로 분류할 수 있다.

Linter: 소스 코드를 분석하여 프로그램 오류, 버그, 스타일 오류, 의심스러운 곳에 표시하는 도구
Prettier: 정해놓은 규칙대로 자동으로 포맷 정렬하는 도구

나 또한 코드 규칙을 설정하여 사용하고 있다. 이 글에서는 “코드 검사 설정 / Commit Message 검사 설정 / Editor 설정 / 마치며” 로 분류하여 사용하고 적용한 방법에 대해 작성해보고자 한다. 추가로 이러한 활동을 통해 개발자들의 성장, 고객 만족에 대해 경험했던 내용에 대해서 작성해보고자 한다.

코드 검사 설정

코드 검사 실행

코드 포매터, 문법검사 등을 실행하기 위해서는 특정 시점에서 실행할 수 있는 스크립트가 필요하다. Git에는 “어떤 이벤트가 생겼을 때 자동으로 특정 스크립트를 실행” 할 수 있는 Git Hooks 라는 기능을 제공한다.

husky 라는 패키지는 Git hook을 쉽게 실행할 수 있도록 제공하며 Git stage 상태에 있는 코드들만 검사하도록 하는 lint-staged 라는 패키지를 사용하면 버전 관리 대상 파일들만 규칙 검사를 실행할 수 있다.

정리하자면 아래와 같다.

husky: git hook 실행 시 별도 명령어 실행할 수 있도록 제공
lint-staged: Git stage에 있는 코드들의 포맷 및 문법 검사할 수 있도록 제공

코드 검사 / 포매팅

위의 lint-staged를 이용해 Git stage 상태에 있는 javascript(.js, .jsx), typescript(ts, .tsx), css, scss, vue 등의 코드 검사를 아래 도구들을 이용해 실행할 수 있다.

prettier: 코드 포매터 (PHP를 이용할 경우 prettier-php를 설치하여 사용)
eslint: 코드 검사 (javascript, typescript, vue 코드 검사)
stylelint: css, scss 내 style 코드 검사 (#참고)

Javascript 뿐만 아니라 타 언어(PHP, go, python, …)역시 코드 검사를 위한 별도 패키지들을 제공한다. PHP로 개발할 경우 phpstan (Laravel은 larastan 사용) 설치한 후 lint-staged 스크립트 내 php 코드 검사할 수 있도록 구성할 수 있다. 나는 아래와 같이 docker를 이용해 검사할 있도록 구성하였다.

// .lintstagedrc.cjs
const path = require("path");

module.exports = {
    "**/*.php": (absolutePaths) => {
        const cwd = process.cwd();
        const relativePaths = absolutePaths
            .map((file) => path.relative(cwd, file))
            .join(" ");

        return [
            // Prettier 적용
            `npm run prettier ${relativePaths}`, // --write 옵션 추가 가능

            // Container 명령어 실행
            // @see https://dev.to/nitzano/linting-docker-containers-2lo6
            `docker compose -f docker-compose-local.yml exec app sh -c "./vendor/bin/phpstan --memory-limit=256M analyse ${relativePaths}"`,
        ];
    },
};

코드규칙 기반 자동수정

코드 검사 및 포매팅하는 도구들은 추가 옵션을 이용해 개발자 개입 없이 자동으로 수정하는 기능을 제공한다.

eslint는 —fix, prettier는 —write, stylelint 는 —fix 옵션을 통해 자동 코드 문법 수정 및 포매팅 수행

구글링으로 검색된 많은 글에서 이와 같은 옵션들을 추가하여 안내하는 글들을 많이 볼 수 있고 실제 사용 시 편리하나, 개인적으로는 아래와 같은 이유에서 현재는 사용하지 않는 것으로 설정하였다.

eslint, stylelint의 자동수정 옵션을 켜면 내가 작성한 코드에서 틀린 부분이 왜 바뀌었는지 확인할 수 없음
- 추가로 개발자의 성장을 방해하는 요소라 판단하였음 (협업 시 틀린 부분 등에 대한 확인 및 수정 과정 반복을 통해 성장할 수 있기 때문)
prettier: commit 시 자동으로 포매팅 하도록 설정하면 내가 수정한 코드가 아닌 변경된 코드가 반영될 수 있기 때문에 혼동이 생길 수 있음
- format on save 옵션을 활성화 하여 사용할 경우, 저장 시 자동으로 포맷이 변경되어 저장되기 때문에 —write 옵션이 사실상 불필요함

Commit Message 검사 설정

코드 규칙도 중요하지만, 내가 작성한 코드에 대한 메시지(커밋 메시지)를 규칙을 정해 작성하는 것 또한 중요하다. commitlint 를 사용하면 간단히 commit message 규칙 검사를 설정 할 수 있다. 현재 가장 많이 사용되는 conventional commit 규칙도 같이 설치하여 사용 할 수 있다.

참고로, vscode 안에서 commit 메시지 작성 시 conventional commit extension을 사용하면 안내에 따라 쉽게 작성할 수 있다.

사람은 글보단 그림으로 이해를 빠르게 하기 때문에 gitmoji 도 같이 사용한다면 해당 commit 목적을 이해하는데 도움이 된다.

업무번호 추가

업무 추적을 위해 커밋 메시지 앞 혹은 뒤에 jira ticket 번호, github issue 번호, 기타 업무관련 id 등 업무 단위를 넣어 반영하기도 한다. 이는 해당 이슈를 어떻게 처리하였는지에 대한 추적을 용이하게 해주기 때문에 많은 곳에서 사용하고 있다.

개인적인 경험으로는 업무 관련 Branch를 생성하여 작업을 완료한 후 Pull Request → Merge 시 Branch가 삭제되면 해당 업무에 대한 추적이 쉽지 않기 때문에 이러한 업무 단위(번호)를 추가하여 사용하는 것이 도움이 된다.

jira와 commitlint + conventional commit을 적용하고 있다면 구글링을 통해 찾은 이 글 등을 참고하여 쉽게 적용할 수 있다. 헤이딜러 블로그에서도 관련 내용을 안내하고 있다.

개발도구(IDE) 설정

팀별로 개발 도구(IDE)를 통일하여 사용하는 곳도 있지만, 아닌 곳도 있는데 이는 회사 / 팀 성향에 따라 달라지는 것 같다. 내가 있는 팀은 자연스럽게 라이센스에 문제가 없는 선에서 자유롭게 사용하고 있다.

editorconfig를 이용하면 개발자 개인이 사용하는 개발도구 에디터 설정(텍스트 편집기)을 동일하게 맞춰 사용하는 것이 개발자들 간 일관된 코딩 스타일을 유지하는데 도움이 된다. 예를 들어 파일별 들여쓰기 스타일 (tab or space), 줄의 끝 문자(CR/LF), 인코딩 (UTF-8등) 등을 어떤 IDE를 사용하던지 공통으로 적용할 수 있다.

최근 각 프레임워크들의 Starter Kit, Boilerplate 등은 이를 기본으로 제공하고 있다.

마치며

이상 설정하여 사용하고 있는 코드 규칙 등에 대한 내용을 작성하였다. 위의 내용들은 많이 알려져 있기 때문에 구글링을 통해 손쉽게 설치하고 설정할 수 있는 방법을 찾을 수 있다.

사실 이러한 것들을 적용하지 않아도 개발하는데는 문제가 없고, 해 왔으며, 할 수 있다. 그렇다면 왜 사용해야 하는가? 에 대한 의문이 드는데, “품질” 이라는 것으로 수렴할 수 있을것 같다.

개발자도 사람이기 때문에 시간의 흐름 과정에서 일관된 규칙을 지키는 것이 힘듬. 때문에 강제로 적용하여 사용하는 것이 일관된 품질을 유지할 수 있음
포맷 정렬만 잘 해도 가독성을 향상시킬 수 있어 향후 유지보수가 용이해짐
개발 과정에서 오류를 빠르게 확인하여 고칠 수 있음
개발자들의 성장에 긍정적인 영향을 미치고 좋은 결과물을 만들 수 있음. 이는 그것을 받는 고객들의 만족도를 높일 수 있음

코드 규칙은 업무의 최종 목표인 고객들의 만족도를 높일 수 있는 방법 중 하나이며 개발자들이 만족할 수 있는 환경 안에서 좋은 결과가 나올 수 있다고 생각한다. 또한 유지보수도 손쉽고 빠르게 할 수 있는 있게 되어 고객 만족은 더욱 높아질 수 있다.

개인적인 경험으로는 이를 적용했을 때와 적용하지 않았을 때 큰 차이가 있었는데, 특히 혼자서 하는 개발이 아닌 협업을 하는 개발자들이 전부 성장하는 경험을 할 수 있었다. 간단한 예를 들자면 아래와 같다.

prettier 사용 시 코드 포맷 자동 정렬이 적용될 때와 되지 않을 때의 체감이 컸다. 자동 정렬이 적용되지 않으면 코드 내 오류가 있다는 의미이기 때문에 다시 한번 더 확인하게 되는 습관을 가질 수 있게 되었다.
에디터랑 연결되어 오류를 알려주는 linter 를 적용하니 오류 발생 시 나타나는 빨간 밑줄을 없애려고 수정하고 적용하는 습관을 가지게 되었다.
PHP 코드의 경우, phpstan은 주석하고 연결되어 코드 검사를 해 주기 때문에 주석에 잘못된 매개변수 data type 등이 있으면 틀렸다고 알려주기 때문에 정확한 코드를 만들 수 있게 되었다.

추가로 웹 디자인하시는 분들이 퍼블리싱을 같이 할 경우(내가 있는 곳에선 vue로 퍼블리싱을 해주신다), 이와 같은 규칙을 적용해드리니 처음엔 어색해했지만 시간이 지나니 stylelint를 이용한 빨간 밑줄을 확인하고 수정할 수 있었고 코드 자동 정렬이 되는 부분에 대해 만족했다고 하였다.

즉 내부 구성원들의 만족도 또한 같이 높아지게 되며, 신뢰성이 높아질 수 있는 계기가 되는 것 같다는 생각이 들었다.

linter, prettier 세부적인 설정을 한 것이 아니라 기본적인 설정만 진행했음에도 고객 및 개발자들의 만족도가 올라갔다. 심지어 이러한 설정이 없으면 불편하게 되었을 정도이다. 프로젝트 특성에 따라 세부적인 설정을 진행한다면 훨씬 만족도가 높아질 것 같으며, 향후 몇 가지 찾아보고 적용해보고자 한다.

고민해봐야 할 것

그럼에도 불구하고 코드 검사 규칙은 무조건 적용할 수는 없는 환경들이 존재한다. 개인적인 경험으로, legacy 코드에 자동으로 코드 포매팅을 하여 운영에 반영했을 때 오류가 발생하여 철회하였다 (php, html, css, javascript 등이 하나의 파일 내 혼합되어 구현되어 있을 경우 prettier를 적용하여 반영하니 오류가 발생하였다). 그래서 husky, lint-staged, commitlint 만 적용하고 나머지는 전부 사용하지 않는 것으로 하였다.

코드 검사 규칙과 같은 도구에서 잡아줄 수 없는 것들 또한 여전히 존재한다. Layered Architecture (Repository, Service, DTO로 구현되는 구조), 프로젝트 폴더 구조, 구현 방법 등은 팀 내에서 정의해서 사용한 후 코드 리뷰 등의 과정을 거쳐 수정 및 개선을 할 수 밖에 없다.

최근 다양한 ChatGPT, Github Copilot, Cursor AI 등을 통해 도움을 받을 수 있는 환경이 제공되긴 하지만 최종 검수 및 적용은 개발자가 해야 한다. AI가 좋은 결과를 만들어 제공해주지만, 그럴싸하게 만들어내는 환각(Halluciation) 현상을 확인하고 걸러내야 하기 때문에 이를 이용하는 개발자의 꼼꼼함, 실력이 반드시 필요할 수 밖에 없어 오히려 더 어려운 환경이 된 것이 아닌가 싶기도 하다.

코드 개발 규칙들을 적용하여 개발해보자