코딩 표준을 도입하자고 하면 “지금도 잘 돌아가는데” 라는 반응이 먼저 나옵니다. 맞는 말입니다 — 표준을 지킨다고 코드가 더 빨라지지도, 버그가 저절로 사라지지도 않습니다. 실익은 다른 곳에 있습니다. 리뷰에서 서식 이야기가 사라지는 것입니다.
실익은 정돈이 아니라 주의력입니다
표준이 없는 저장소의 리뷰는 이렇게 흘러갑니다. “여기 들여쓰기가 다른데요”, “이 괄호 위치는 저랑 다르네요”, “함수 이름 규칙을 정하죠”. 이 대화들은 전부 취향의 교환이고, 결론이 나도 다음 파일에서 다시 시작됩니다.
더 나쁜 것은 이 대화가 주의력을 먼저 소모한다는 점입니다. 사람이 코드를 집중해서 볼 수 있는 시간은 길지 않은데, 그 앞머리를 공백과 괄호에 쓰면 정작 봐야 할 것 — 이 변경이 의도와 맞는가, 놓친 경계 조건이 있는가 — 에 남는 힘이 줄어듭니다.
표준의 진짜 값은 여기입니다. 어느 쪽이 옳은지는 중요하지 않고, 정해져 있다는 사실이 중요합니다. 그리고 정해진 것을 사람이 지적하지 않아야 합니다 — 도구가 지적해야 아무의 주의도 쓰이지 않습니다.
무엇을 정하는 표준인가
워드프레스 코딩 표준은 PHP · HTML · CSS · JavaScript 네 가지를 다루고, 실제로 매일 걸리는 것은 PHP 쪽 규칙들입니다. 크게 세 묶음입니다.
서식 — 들여쓰기는 탭, 괄호 안쪽에 공백, 배열은 짧은 문법. 이 묶음은 자동 교정이 가능하므로 사람이 손댈 일이 거의 없습니다.
명명 — 함수와 변수는 소문자 밑줄, 클래스는 대문자 시작, 파일 이름 규칙. 프로젝트 접두사 규칙을 여기에 얹어 쓰는 경우가 많습니다.
안전 — 이 묶음이 표준을 도입할 실제 이유입니다. 출력 이스케이프 누락, 입력 sanitize 누락, $wpdb 직접 쿼리에서 prepare() 미사용, nonce 검증 누락을 규칙집이 지적합니다. 서식 규칙만 보고 “취향 문제” 로 생각했다면, 이 묶음이 판단을 바꿉니다.
도구로 강제하기
설정은 짧습니다. 프로젝트에 개발 의존성으로 규칙집을 설치하고, 규칙 파일을 저장소에 두면 끝입니다.
composer require --dev wp-coding-standards/wpcs
dealerdirect/phpcodesniffer-composer-installer
vendor/bin/phpcs # 검사
vendor/bin/phpcbf # 자동 교정규칙 파일(phpcs.xml.dist)을 저장소에 두는 것이 중요합니다. 설정이 각자의 편집기에만 있으면 사람마다 다른 규칙으로 검사하게 되고, 그러면 표준이 있는 것이 아니라 표준에 대한 의견이 여러 개 있는 것입니다.
<?xml version="1.0"?>
<ruleset name="Acme">
<file>.</file>
<exclude-pattern>vendor/*</exclude-pattern>
<exclude-pattern>node_modules/*</exclude-pattern>
<rule ref="WordPress"/>
<config name="minimum_wp_version" value="6.0"/>
<rule ref="WordPress.WP.I18n">
<properties>
<property name="text_domain" type="array" value="acme"/>
</properties>
</rule>
</ruleset>그다음 세 자리에 붙입니다. 편집기에 붙이면 타이핑 중에 보이고, 커밋 훅에 붙이면 변경된 파일만 빠르게 검사되며, CI 에 붙이면 우회할 수 없는 마지막 관문이 생깁니다. 셋 다 있으면 가장 좋지만, 하나만 고르라면 CI 입니다 — 나머지는 개인 설정이라 빠질 수 있습니다.
도입 순서 — 한 번에 다 고치지 않습니다
기존 코드가 있는 저장소에 표준을 켜면 경고가 수천 건 나옵니다. 여기서 전부 고치려 들면 거대한 변경 하나가 생기고, 그 커밋은 리뷰가 불가능하며 기능 변경과 섞이면 사고의 원인이 됩니다.
실무적인 순서는 이렇습니다. 먼저 새로 쓰는 코드에만 검사를 겁니다 — 변경된 파일만 검사하도록 CI 를 구성하면 기존 코드는 건드리지 않고 시작할 수 있습니다. 그다음 자동 교정이 가능한 서식 규칙만 골라 순수 서식 커밋으로 한 디렉터리씩 정리합니다. 이 커밋에는 기능 변경을 절대 섞지 않습니다. 마지막으로 안전 규칙의 남은 경고를 목록으로 만들어 하나씩 처리합니다 — 이쪽은 서식이 아니라 실제 결함일 수 있으므로 급하게 일괄 처리하지 않습니다.
규칙을 예외 처리해야 할 때는 이유를 함께 적습니다. 무조건 억제하는 주석이 늘어나면 검사 결과가 곧 신뢰를 잃습니다.
표준 검사와 함께 걸어 두면 좋은 것이 PHP 버전 호환성 검사입니다. 지원해야 하는 하한 버전을 지정해 두면, 최신 문법이 섞여 들어오는 것을 배포 전에 잡습니다.
검사를 CI 에 얹는 구체적 구성은 로컬에서 프로덕션까지 연재에서 다루고, 관련 글은 개발 워크플로우 아카이브에 모여 있습니다. 이미 쌓인 코드의 품질과 취약점을 함께 정리해야 한다면 최적화 지원 사업에 PHP 소스 정리가 포함돼 있습니다.