Steering Zig Fmt — 개발자가 알아야 할 핵심 정리

Steering Zig Fmt — 개발자가 알아야 할 핵심 정리

Zig 코드를 자동으로 포맷팅하는 zig fmt의 숨겨진威力

Zig의 공식 포매터 zig fmt는 단순한 코드 정렬 도구가 아니다. 선택적 포매터(steerable formatter)로서, 개발자가 원하는 레이아웃을 파일 자체에 기록해두면 그대로 반영한다. 이 특성을 잘 활용하면 자동 서식과 개인 취향 사이의 균형을 완벽하게 잡을 수 있다.

Trailing Comma로 함수 호출 레이아웃 조절하기

가장 직관적인 조작 방법은 trailing comma를 활용하는 것이다.

// ❌ trailing comma 없음 → 한 줄로 정렬

foo(a, b, c, d, e, f)

// ✅ trailing comma 있음 → 여러 줄로 분할
foo(
a,
b,
c,
d,
e,
f,
)

zig fmt는 trailing comma의 유무를 신호로 해석한다. 쉼표가 없으면 "이 함수는 한 줄로 표현 가능하다는 뜻"이라고 판단해 한 줄로 정리하고, 쉼표가 있으면 "개발자가 여러 줄을 의도했다"라고 받아들여 각 인자를 줄바꿈한다.

함수 시그니처가 긴 경우, 파라미터 각각을 새 줄에 배치하면 가독성이 크게 향상된다. 특히 3개 이상의 인자를 받는 함수에서는 trailing comma 전략이 유용하다.

// trailing comma로 멀티라인 유도

const result = calculate(
initial_value,
multiplier,
offset,
tolerance,
);

Columnar Array Layout: 첫 번째 줄바꿈이 기준이 된다

배열이나 리스트의 레이아웃을 조절할 때, 많은 포매터는 정해진 컬럼 수나 너비 제한에 의존한다. 그러나 zig fmt는 첫 번째 줄바꿈의 위치를 기준으로 이후 줄의 아이템 수를 결정한다.

// 4개 아이템에 줄바꿈 적용

const letters = &[_]u8{
'a',
'b',
'c',
'd',
};

첫 번째 아이템 'a' 앞에 줄바꿈을 넣으면, zig fmt는 이후 줄도 같은 개수의 아이템을 유지한다. 만약 첫 번째 줄에 아이템을 추가하고 싶다면:

// ++ 연산자로 라인당 아이템 수 조절

const data = &[_]u8{ 'a', 'b', 'c', 'd' } ++
&[_]u8{ 'e', 'f', 'g', 'h' };

++ 연결 연산자를 사용하면 배열을 결합하면서 각 그룹별 아이템 수를 독립적으로 제어할 수 있다. 이 기법은 데이터를 논리적 그룹으로 나눌 때 유용하다.

Container Declarations: 구조체와 열거형의 레이아웃

구조체와 열거형 선언에서도동일한 원리가 적용된다.

// ❌ 한 줄 정렬

const Point = struct { x: f64, y: f64 };

// ✅ 여러 줄 + trailing comma
const Point = struct {
x: f64,
y: f64,
};

trailing comma가 있으면 구조체 멤버가 각각 줄바꿈되며, 없으면 한 줄로 컴팩트하게 정리된다. 이 규칙은 enum과 union 선언에도 동일하게 적용된다.

zig fmt 지시어로 포맷팅 비활성화하기

자동 서식을 원치 않는 코드 블록이 있다면 // zig fmt: off와 // zig fmt: on으로 감싸면 된다.

// zig fmt: off

const weird_format = &[_]u8{'a','b','c','d','e','f'};
// zig fmt: on

이 지시문 사이의 코드는 zig fmt가 건드리지 않는다. 그러나 지시문 자체는 정규화되어 항상 동일한 형태(// zig fmt: off)로 정리된다.

실무에서의 활용 전략

1. 프로젝트 전반에 일관된 스타일 적용

모든 Zig 프로젝트에서 zig fmt를 사용하면 코드 스타일 논쟁에서 자유로워진다. 팀원 각자가 원래 선호하는 포맷이 있더라도, 파일의 trailing comma 유무로 미세 조정이 가능하기 때문에 충돌이 적다.

2. 리팩토링 시 레이아웃 전환

함수 인자가적은에서많은으로 변경될 때, trailing comma만 추가하면 자동으로 멀티라인 포맷으로 전환된다. 리팩토링 노동을 줄이는 동시에 일관된 스타일을 유지할 수 있다.

3. 데이터 테이블 정의

구성 데이터나 매핑 테이블을 정의할 때 columnar layout을 활용하면 시각적으로 구분하기 쉬운 표 형태의 코드를 만들 수 있다.

요약

zig fmt의 핵심은 개발자의 의도를 파일에 담을 수 있다는 점이다. trailing comma로 함수 호출 형태를 조절하고, 첫 번째 줄바꿈 위치로 배열 레이아웃을 결정하며, ++ 연산자로 그룹핑을 제어한다. 이 세 가지 기법을 조합하면 대부분의 서식 상황을 오류 없이 다룰 수 있다.

Zig의 포매터는 규칙을 강요하는 것이 아니라, 개발자가 세운 기준을 충실히 따르는 동반자다. 이 특성을 이해하면 자동 서식과 개인 취향 사이의 긴장을 자연스럽게 해소할 수 있다.

tags: Zig, zig fmt, 포매터, 코드 스타일, 프로그래밍, 개발도구, 코딩, 튜토리얼

---

📚 출처

• Steering Zig Fmt - matklad (daily.dev)