네이밍 컨벤션

이름을 짓는 사람이 여럿이면 이름은 저절로 갈라집니다. 웹 화면을 맡은 개발자는 문서 공유를 doc_shared 라고 적고, 앱을 맡은 개발자는 같은 행동을 shareDocument 라고 적고, 나중에 붙은 확장 프로그램에서는 Document Shared 로 들어갑니다. 셋 다 자기 코드에서 쓰던 방식을 가져왔을 뿐입니다.

갈라졌다는 사실은 세는 자리에서야 드러납니다. 이벤트는 언제 누가 무엇을 했는지를 한 줄로 남긴 기록인데, 이 줄을 모아 세려면 같은 행동이 같은 이름을 달고 있어야 합니다. 지난달 공유가 몇 번 일어났는지 물으면 분석 도구는 doc_shared 가 달린 줄만 세어 돌려줍니다. 나머지 두 이름으로 쌓인 기록은 다른 행동으로 취급돼 빠집니다. 답이 실제보다 작게 나오고, 작게 나왔다는 사실조차 한참 뒤에 발견됩니다.

이 불편은 되묻는 말로 나타납니다. 지현이 "공유가 지난달에 얼마나 늘었죠" 하고 물으면 태오가 "어느 이름 기준으로요" 하고 답합니다. 숫자 하나를 얻는 데 이름 목록부터 맞춰야 합니다.

네이밍 컨벤션은 이 갈라짐을 심기 전에 막으려고 정해 두는 몇 줄짜리 규칙입니다. 이름을 잘 짓게 만드는 장치가 아니라 이름이 한 가지로만 지어지게 만드는 장치입니다. 무엇을 남길지 고르는 일은 트래킹 플랜이 맡고, 고른 것에 어떤 형식으로 이름을 붙일지는 이 규칙이 맡습니다.

들어가는 항목은 대개 다섯이고, 규칙 전체가 한 화면을 넘지 않습니다.

1. 표기 방식 — 소문자와 밑줄만 쓸지, 낱말을 붙여 쓰면서 대문자로 끊을지를 하나로 정합니다. doc_shared 와 docShared 와 DocShared 는 분석 도구에서 서로 다른 이름이라, 한 가지를 고르는 것만으로 갈라짐의 절반이 사라집니다.
2. 낱말 순서 — 대상을 먼저 쓰고 동작을 뒤에 붙이는 식으로 자리를 고정합니다. doc_shared, comment_added, invite_sent 처럼 맞춰 두면 사전순으로 늘어놓았을 때 같은 대상이 한자리에 모입니다.
3. 시제 — 이미 일어난 일을 남기는 기록이니 동작은 과거형으로 통일합니다. share 와 shared 와 sharing 이 섞이면 앞의 두 규칙을 지킨 이름끼리도 셋으로 갈립니다.
4. 낱말 사전 — 같은 대상을 부르는 말을 하나만 남깁니다. doc 과 document 와 file 이 한 제품에 섞여 있으면 형식이 같아도 이름은 달라집니다. 화면에서 같은 개념을 늘 같은 낱말로 부르는 용어 일관성과 여기서 기준을 맞춰 둡니다.
5. 속성 이름 규칙 — 이벤트 속성에도 같은 규칙을 겁니다. 이벤트 속성은 기록 한 줄에 딸려 붙는 부가 정보로, 공유했다는 사실 옆에 공유 방식이나 문서 종류를 적어 두는 칸입니다. 여기에는 단위를 이름에 넣으라는 항목이 하나 더 붙습니다. duration 이라고만 적으면 값이 초인지 밀리초인지 아는 사람은 심은 사람뿐입니다.

이름에 넣지 않을 것을 적는 줄도 함께 들어갑니다. 사용자 이메일처럼 사람을 특정하는 값은 여기서 막습니다.

쓰는 사람은 데이터를 맡은 쪽이고, 읽는 사람은 기록을 심는 개발자입니다. 구성원이 마흔 명 안팎인 회사에는 데이터 전담 담당자가 없어 기능을 맡은 기획자가 자기 기능의 기록까지 함께 정합니다. 페이지덱에서는 지현이 초안을 잡고 태오가 실제 코드에서 그렇게 적히는지 확인합니다. 규칙을 정하는 자리에 심는 손이 없으면 지키기 번거로운 규칙이 나오고, 그런 규칙은 두 달 뒤에 아무도 지키지 않습니다.

읽는 쪽은 세 부류입니다.

1. 기록을 심기 직전의 개발자 — 가장 자주 읽습니다. 같은 행동이라도 클라이언트 수집으로 사용자 기기에서 나가기도 하고 서버 수집으로 서버에서 나가기도 하는데, 보내는 자리가 달라도 이름은 같아야 합니다.
2. 지표를 만드는 사람 — 이름만 보고 그 줄이 무엇을 센 것인지 짐작할 수 있어야 합니다. 규칙이 지켜진 제품에서는 doc_ 로 시작하는 이름만 모으면 됩니다.
3. 나중에 합류한 사람 — 이름을 지은 사람이 떠난 뒤에도 규칙이 남아 있으면 기존 이름을 해석할 수 있습니다.

읽히는 시점이 코드를 짜기 직전이라 문서는 짧아야 합니다. 한 화면을 넘어가면 열어 보지 않고 심는 사람이 생깁니다. 새 이름을 누가 검토할지도 한 사람으로 정해 둡니다.

"이벤트 이름 컨벤션에 맞춰 주세요. 대상을 앞에 쓰고 동작을 뒤에 붙이는 순서입니다."

이름이 틀렸다는 말이 아니라 형식이 어긋났으니 심기 전에 고치라는 요청입니다.

"그 이름은 컨벤션 정하기 전에 심은 거라 저렇습니다. 지금은 그대로 둡니다."

바꾸면 지난 기록과 이어 볼 수 없어 옛 이름을 남겨 둔다는 뜻입니다.

"속성 이름에 단위 좀 넣어 주세요. duration 말고 duration_sec 으로요."

값이 초인지 밀리초인지 이름만 보고 알게 해 달라는 요청입니다.

페이지덱에서는 새 기능의 기록을 심기 전에 태오가 이름 후보를 지현에게 한 줄로 보냅니다. 검토는 오 분 안에 끝나고, 어긋난 이름은 코드에 들어가기 전에 잡힙니다. 심고 난 뒤에 발견하면 이름을 고치는 대신 옛 이름과 새 이름을 묶어 읽는 예외를 트래킹 플랜에 적습니다.

형식 취향 문제라고 보는 경우가 가장 많습니다. 밑줄을 쓰든 대문자로 끊든 사람 눈에는 같은 말로 읽히니 팀마다 달라도 되겠다고 생각하게 됩니다. 그런데 세는 쪽은 사람이 아니라 분석 도구라서, 글자가 하나만 달라도 다른 이벤트로 취급합니다. 그대로 두면 반년 뒤 공유 횟수를 묻는 질문에 세 이름을 찾아 더해야 답할 수 있고, 하나를 빠뜨렸다는 사실은 눈에 띄지 않습니다. 차단이나 오류로 기록이 도착하지 못하는 수집 유실과는 다른 문제입니다. 기록은 다 도착했는데 세는 쪽이 못 찾을 뿐입니다.

이름은 나중에 정리하면 된다는 생각도 자주 봅니다. 글자라서 코드 한 줄만 고치면 바뀔 것처럼 보이지만, 이미 저장된 기록의 이름은 소급해서 바뀌지 않습니다. 바꾼 날을 기준으로 지표가 끊기고, 석 달 전과 나란히 놓으려면 두 이름을 합쳐 읽는 예외를 만들어야 합니다.