코드 컨벤션은 왜 생겼고, 왜 중요한가

코드 컨벤션은 여러 사람이 같은 코드를 오래 읽고 수정하기 위한 약속이다. 컴파일러가 이해하는 코드를 넘어, 동료가 예측 가능한 방식으로 이해할 수 있는 코드를 만드는 데 목적이 있다.

생겨난 배경

코드 컨벤션은 한 사람이 특정 시점에 발명한 개념이라기보다, 공동 개발과 유지보수에서 반복되는 문제를 해결하며 발전한 관행이다.

문법에 맞는 코드라도 이름, 들여쓰기, 파일 배치, 작성 방식은 사람마다 달라질 수 있다. 이런 차이가 쌓이면 코드를 읽을 때마다 작성자의 습관부터 파악해야 한다. 작성자가 떠나거나 담당자가 바뀌면 그 비용은 더 커진다.

그래서 조직과 언어 공동체는 반복해서 사용할 작성 기준을 문서로 정리했다. 예를 들어 Sun의 1997년 Java 코드 컨벤션은 유지보수와 작성자 이외의 개발자가 코드를 읽는 상황을 주요 배경으로 설명한다. 이는 컨벤션의 최초 기원이라기보다, 그 필요성을 보여주는 오래된 공식 사례다. Sun Java Code Conventions

중요한 이유

목적	실제 효과
읽는 비용 감소	이름과 배치가 익숙해져 업무 로직에 집중할 수 있다
협업과 인수인계	작성자가 달라도 코드를 찾고 수정하는 방식이 비슷해진다
리뷰 효율	표현 방식에 대한 논쟁을 줄이고 설계와 오류에 집중한다
변경 안정성	불필요한 형식 변경이 줄어 실제 변경점을 파악하기 쉽다
팀 경험의 축적	반복된 리뷰와 시행착오를 다음 작업의 기준으로 남긴다

Google의 스타일 가이드도 독자를 위한 명확성과 코드베이스의 일관성을 강조한다. Google Go Style Guide

무엇까지 컨벤션인가

팀에서는 여러 기준을 통틀어 코드 컨벤션이라고 부르기도 하지만, 성격을 구분하면 관리하기 쉽다.

구분	예시	관리 방법
표현 규칙	들여쓰기, 이름, import 순서	포매터·린터로 자동화
구현 관례	예외 처리, 응답 형식, 공통 유틸 사용	템플릿·리뷰·테스트
설계 원칙	계층 책임, 트랜잭션 경계, 의존 방향	설계 문서·ADR·리뷰
업무 계약	중복 허용 여부, 삭제 정책, 상태 전이	명세·테스트

모든 기준을 포매터로 강제할 수는 없다. 반대로 기계가 처리할 수 있는 형식 문제를 사람이 매번 리뷰할 필요도 없다.

개인 취향과 팀의 약속은 다르다

개인이 편하게 느끼는 방식이 팀 전체에도 가장 좋은 방식이라는 보장은 없다. 팀의 컨벤션은 구성원이 함께 이해하고 유지할 수 있어야 한다.

리뷰에서 발견한 수정 사항도 구분해야 한다.

• 이번 업무 조건에서만 필요한 수정인가?
• 반복해서 적용할 가치가 있는 공통 원칙인가?
• 기존 규칙의 문제인가, 규칙을 잘못 적용한 것인가?

한 번의 수정 사례를 곧바로 전체 규칙으로 만들면 예외와 제약이 계속 늘어난다. 규칙에는 적용 범위와 이유가 필요하며, 효과가 없는 규칙은 줄일 수 있어야 한다.

AI 개발에서의 의미

AI는 코드를 빠르게 생성하지만, 같은 요구에도 서로 다른 구조와 표현을 선택할 수 있다. 컨벤션과 템플릿은 그 선택 범위를 줄이고 결과를 예측 가능하게 만든다.

하네스에는 이 기준을 AI가 언제 읽고 어떻게 적용할지 담을 수 있다.

팀이 합의한 설계 원칙과 계약
              ↓
코드 컨벤션과 검증된 템플릿
              ↓
하네스가 필요한 기준을 선택
              ↓
AI가 구현하고 테스트로 검증
              ↓
리뷰에서 발견한 개선안을 팀이 검토

여기서 AI가 작업 경험을 학습하는 것과 조직의 공통 규칙을 변경하는 것은 별개의 권한이다. 개인의 수정 취향이나 특정 작업의 성공이 곧 팀 표준이 되어서는 안 된다.

코드 컨벤션의 가치는 모든 코드를 똑같이 만드는 데 있지 않다. 다음 사람이 이해하고 변경하는 데 필요한 비용을 줄이고, 팀이 쌓은 판단을 지속해서 활용할 수 있게 하는 데 있다.