“코드 정합성(Code Integrity)”, 나중에 고치려면 더 힘듭니다

들어가며

처음에는 분명 간단했던 코드가 있습니다.

변수 이름도 몇 개 없고, 함수도 많지 않고, 파일 구조도 단순합니다. 그런데 프로젝트가 몇 달 지나고 개발자가 한두 명씩 추가되기 시작하면 상황이 달라집니다.

비슷한 기능인데 변수 이름이 다르고, 같은 데이터를 처리하는 방식도 조금씩 달라집니다.

어떤 곳에서는 userId를 사용하고 다른 곳에서는 user_id를 사용합니다.

응답 데이터도 어떤 API에서는 data로 내려주고 다른 API에서는 result라는 이름을 사용합니다.

처음에는 별 문제가 없어 보입니다.

하지만 이런 차이가 하나둘 쌓이면 어느 순간 코드 수정이 상당히 어려워집니다.

이때 자주 이야기되는 개념이 바로 코드 정합성(Code Integrity / Consistency)입니다.

코드 정합성이란 무엇일까?

코드 정합성이라는 표현은 문맥에 따라 조금 다르게 사용됩니다.

일반적으로는 코드가 의도한 규칙과 구조를 유지하면서 서로 모순되지 않고 일관되게 동작하는 상태를 의미한다고 이해하면 쉽습니다.

특히 개발 현장에서는 Code Integrity와 Code Consistency를 구분해서 사용하는 경우가 있습니다.

Code Integrity는 코드가 임의로 손상되거나 예상하지 못한 방식으로 변경되지 않고 정상적인 상태를 유지하는 것에 가깝습니다.

반면 Code Consistency는 프로젝트 안에서 코드 작성 방식과 구조, 네이밍, 데이터 처리 방식 등을 일정한 기준으로 유지하는 것에 좀 더 가깝습니다.

실제 프로젝트에서는 두 개념이 서로 연결되어 있습니다.

코드가 일관되게 작성되어 있으면 수정하기 쉽고, 잘못된 변경을 발견하기도 쉬워집니다.

코드 정합성이 깨지면 어떤 문제가 생길까?

가장 흔한 문제는 유지보수입니다.

예를 들어 사용자 정보를 조회하는 코드가 있다고 생각해보겠습니다.

const userId = 100;

그런데 다른 개발자가 비슷한 코드를 만들면서 이렇게 작성했습니다.

const user_id = 100;

또 다른 파일에서는

const id = 100;

를 사용합니다.

기능적으로는 큰 문제가 없을 수 있습니다.

하지만 프로젝트 규모가 커지면 이야기가 달라집니다.

검색을 통해 userId를 찾았는데 관련 코드가 모두 검색되지 않습니다.

반대로 id를 검색하면 너무 많은 결과가 나옵니다.

결국 코드를 이해하는 데 시간이 더 걸립니다.

네이밍 규칙 하나만 정해도 차이가 크다

코드 정합성을 유지하는 가장 쉬운 방법 중 하나가 네이밍 규칙을 정하는 것입니다.

예를 들어 JavaScript 프로젝트에서 변수와 함수는 camelCase를 사용한다고 정할 수 있습니다.

const userId = 100;
const userName = "홍길동";

function getUserInfo() {
    // ...
}

그리고 데이터베이스 컬럼은 snake_case를 사용하기로 정할 수도 있습니다.

user_id
user_name
created_at

이렇게 기준을 명확하게 정하면 코드와 데이터베이스 사이에서 변환이 필요할 때도 규칙을 쉽게 이해할 수 있습니다.

반대로 특별한 이유 없이

userId
user_id
UserId
USER_ID

가 한 프로젝트 안에 섞여 있다면 코드를 읽는 사람은 매번 고민해야 합니다.

작은 차이처럼 보이지만 개발에서는 이런 고민이 반복될수록 생산성이 떨어집니다.

API 응답 형식도 정합성이 중요하다

웹 개발을 하다 보면 API 응답 구조에서도 비슷한 문제가 발생합니다.

예를 들어 어떤 API는 다음과 같이 응답합니다.

{
    "data": {
        "id": 1,
        "name": "홍길동"
    }
}

그런데 다른 API에서는

{
    "result": {
        "id": 2,
        "name": "김철수"
    }
}

처럼 내려준다면 프론트엔드에서는 API마다 다른 처리를 해야 합니다.

물론 모든 API가 반드시 똑같은 응답 구조를 사용해야 하는 것은 아닙니다.

하지만 프로젝트 내부에서 특별한 이유 없이 응답 구조가 제각각이라면 유지보수가 어려워집니다.

가능하다면 공통 응답 형식을 정하고,

{
    "success": true,
    "data": {},
    "message": null
}

처럼 일정한 패턴을 유지하는 것이 좋습니다.

함수의 역할도 명확하게 나누는 것이 좋다

코드 정합성은 단순히 변수 이름만의 문제가 아닙니다.

함수가 어떤 역할을 담당하는지도 중요합니다.

예를 들어 getUser()라는 함수가 사용자 정보를 조회하는 것뿐만 아니라,

사용자 조회
로그 기록
권한 확인
이메일 발송
화면 데이터 변환

까지 모두 처리하고 있다면 나중에 수정하기 어려워집니다.

함수 이름과 실제 동작이 맞지 않기 때문입니다.

getUser()라는 이름을 보고 개발자는 사용자 조회 기능만 수행할 것이라고 예상합니다.

그런데 내부에서 이메일까지 발송한다면 코드를 읽는 사람 입장에서는 상당히 당황스럽습니다.

따라서 함수 이름과 실제 책임을 일치시키는 것도 코드 정합성을 유지하는 중요한 방법입니다.

중복 코드도 정합성을 무너뜨리는 원인이 된다

프로젝트를 개발하다 보면 비슷한 코드가 여러 곳에 생기는 경우가 있습니다.

예를 들어 날짜를 다음과 같이 변환하는 코드가 있다고 해보겠습니다.

const year = date.getFullYear();
const month = date.getMonth() + 1;
const day = date.getDate();

이 코드가 프로젝트의 10개 파일에 들어가 있다면 문제가 생길 가능성이 높습니다.

나중에 날짜 표시 형식을 변경해야 한다면 10곳을 모두 수정해야 합니다.

그중 한 곳을 빼먹으면 같은 서비스 안에서 날짜가 다르게 표시됩니다.

이런 문제를 방지하려면 공통 함수를 만드는 방법이 있습니다.

function formatDate(date) {
    // 날짜 변환 로직
}

그리고 필요한 곳에서는 공통 함수를 사용합니다.

formatDate(createdAt);

이렇게 하면 로직 변경도 한 곳에서 관리할 수 있습니다.

코드 포맷도 생각보다 중요하다

개발자마다 들여쓰기나 괄호 스타일이 다르면 코드를 읽는 것 자체가 피곤해집니다.

예를 들어

function getUser(id){
return users.find(user=>user.id===id);
}

와

function getUser(id) {
    return users.find(user => user.id === id);
}

는 동작 자체에는 큰 차이가 없습니다.

하지만 여러 명이 함께 개발하는 프로젝트라면 두 번째처럼 일정한 스타일을 유지하는 것이 좋습니다.

이런 부분은 사람이 매번 확인하기보다 Prettier 같은 코드 포맷터를 사용하는 방법이 훨씬 편합니다.

개발자가 코드를 저장할 때 자동으로 포맷을 적용하도록 설정하면 개인별 코딩 스타일 차이를 상당 부분 줄일 수 있습니다.

ESLint 같은 정적 분석 도구도 활용할 수 있다

코드 정합성을 유지하려면 사람이 리뷰하는 것만으로는 한계가 있습니다.

그래서 정적 분석 도구를 함께 사용합니다.

JavaScript나 TypeScript 프로젝트라면 ESLint를 활용할 수 있습니다.

예를 들어 사용하지 않는 변수를 검사하거나 특정 코딩 스타일을 강제할 수 있습니다.

const userName = "홍길동";

만 선언하고 실제로 사용하지 않았다면 경고를 발생시키는 식입니다.

팀에서 규칙을 정해두면 개발자가 코드를 작성할 때부터 일정한 기준을 적용할 수 있습니다.

Git에서도 코드 정합성을 관리할 수 있다

코드 정합성은 Git과도 상당히 밀접합니다.

여러 개발자가 같은 파일을 수정하면 코드가 충돌할 수 있습니다.

이때 무작정 코드를 합치는 것보다 변경 내용을 확인하고 의도한 기능이 그대로 유지되는지 확인해야 합니다.

Pull Request를 사용하는 것도 좋은 방법입니다.

개발자 A
   ↓
Branch
   ↓
Pull Request
   ↓
Code Review
   ↓
Merge

이런 과정을 거치면 다른 개발자가 변경 내용을 확인할 수 있습니다.

특히 변수명이나 함수 구조가 기존 프로젝트 규칙과 맞지 않는 부분도 코드 리뷰 과정에서 발견할 수 있습니다.

테스트 코드 역시 정합성을 지키는 장치다

코드가 변경됐을 때 기존 기능이 정상적으로 동작하는지 확인하는 것도 중요합니다.

예를 들어 로그인 기능을 수정했다고 가정해보겠습니다.

로그인 코드만 수정했는데 회원가입이나 사용자 정보 조회 기능까지 문제가 생길 수 있습니다.

이런 문제를 자동으로 확인하려면 테스트 코드가 도움이 됩니다.

코드 수정
   ↓
테스트 실행
   ↓
기존 기능 확인
   ↓
문제 없음
   ↓
배포

테스트가 많다고 무조건 좋은 것은 아니지만 핵심 기능에 대한 테스트가 있다면 코드 변경에 대한 불안감을 줄일 수 있습니다.

결국 중요한 것은 ‘규칙을 정하는 것’

코드 정합성을 이야기하면 처음부터 거창한 개발 프로세스를 만들어야 할 것처럼 느껴질 수 있습니다.

하지만 꼭 그럴 필요는 없습니다.

처음에는 다음 정도만 정해도 충분합니다.

변수명 규칙
함수명 규칙
파일명 규칙
폴더 구조
API 응답 형식
코드 포맷
에러 처리 방식
Git Branch 규칙

그리고 중요한 것은 정한 규칙을 실제 코드에 계속 적용하는 것입니다.

규칙을 문서에만 적어놓고 아무도 지키지 않는다면 의미가 없습니다.

코드 정합성은 프로젝트가 커질수록 더 중요해진다

혼자 만드는 작은 프로젝트에서는 코드 정합성이 크게 중요하지 않다고 느낄 수도 있습니다.

실제로 파일이 몇 개밖에 없다면 조금 지저분한 코드가 있어도 직접 찾아서 수정할 수 있습니다.

하지만 프로젝트가 커지고 개발자가 늘어나면 상황이 달라집니다.

코드가 많아지고 API가 늘어나고 데이터베이스 테이블도 증가합니다.

그때부터는 개발자 한 명의 기억만으로 프로젝트 전체 규칙을 관리하기 어렵습니다.

그래서 초반부터 일정한 규칙을 만들고 자동화할 수 있는 부분은 자동화하는 것이 좋습니다.

결국 코드 정합성은 예쁘게 코드를 작성하기 위한 규칙이 아니라 시간이 지나도 코드를 이해하고 수정할 수 있도록 만드는 장치라고 생각하면 이해하기 쉽습니다.

처음에는 변수명 하나, 함수 구조 하나를 맞추는 것이 귀찮게 느껴질 수 있습니다.

하지만 프로젝트가 커진 뒤 코드를 수정하다 보면 왜 이런 규칙이 필요한지 직접 체감하게 됩니다.

특히 여러 명이 함께 개발하는 프로젝트라면 코드를 작성하는 능력만큼이나 같은 규칙으로 코드를 작성하는 능력도 중요합니다.

오늘 작성한 코드가 내일의 나에게도 읽기 쉬워야 하고, 다른 개발자가 봐도 의도를 쉽게 이해할 수 있어야 합니다.

그런 의미에서 코드 정합성은 개발 초기에 조금 귀찮더라도 반드시 챙겨볼 만한 기본적인 개발 습관입니다.