이전 담당자가 남긴 문서에서 어떤 기능을 찾으려고 grep 했는데 안 나왔다. 나중에 보니 그 기능이 있긴 했고 다른 이름으로 적혀 있었다.
Table of contents
Open Table of contents
이름이 여러 개였다
같은 것을 가리키는 표현을 모아 보니 여섯 가지였다.
결제 연동
PG 연동
페이먼트
payment
pay 모듈
결제 게이트웨이문서마다 다르고 application/libraries 아래 폴더 이름과 SHOW TABLES 에 나오는 이름도 달랐다.
소스 폴더 application/libraries/Payment/
테이블 pg_transaction
설정 키 pay.api_key
화면 메뉴 결제 관리검색하려면 여섯 가지를 다 쳐 봐야 한다. 내가 아는 이름으로 찾으면 그 이름을 쓴 문서만 나오고 나머지가 있다는 것 자체를 모르게 된다.
왜 이렇게 됐나
시기마다 다른 사람이 만들었고 각자 자기 표현을 썼다. 몇 년에 걸쳐 쌓이면서 각자 부르던 말이 그대로 남은 것이다.
그리고 한국어와 영어가 섞였다. 문서는 한국어이고 코드는 영어라 대응이 필요한데 그 대응이 어디에도 없었다. 그 영어도 사람마다 다르게 골라서 pg_transaction 과 pay.api_key 와 Payment 가 함께 쓰였다.
별칭 목록을 만들었다
전부 바꾸는 것은 비용이 컸다. 코드와 표 이름과 문서를 전부 고치려면 RENAME TABLE 까지 돌려야 하고 위험이 크다.
대신 대응표를 만들었다.
## 용어 대응
결제 연동
별칭: PG 연동, 페이먼트, 결제 게이트웨이
코드: application/libraries/Payment/
테이블: pg_transaction, pg_log
설정: pay.*
화면: 관리자 > 결제 관리
배송 연동
별칭: 택배 연동, 딜리버리, 배송사 연동
코드: application/libraries/Delivery/
테이블: delivery_*, courier_*
...검색할 때 이 문서를 먼저 본다. 대응표 하나로 grep 이 되지는 않지만 pg_transaction 을 칠지 Payment 를 칠지는 알 수 있게 됐다.
새로 만드는 것과 옛 이름
옛것은 그대로 두되 새로 만드는 것에는 이름을 정했다.
영문 표기를 정본으로 한다.
payment (pg, pay 안 씀)
delivery (courier, shipping 안 씀)
한국어 표기
payment → 결제
delivery → 배송
폴더·테이블·설정 키에 정본 표기를 쓴다.이것을 정하고 나서 만든 것들은 이름이 일관됐다. 시간이 지나면서 통일된 쪽 비중이 늘어난다.
옛 이름은 전부 바꾸는 대신 기준을 뒀다. 그 파일을 어차피 크게 고칠 때는 겸사겸사 이름도 맞추고 잘 돌고 있고 손댈 이유가 없는 것은 안 바꾼다.
pg_transaction 같은 테이블 이름이 특히 그렇다. RENAME TABLE 을 돌리면 쓰는 곳을 전부 고쳐야 하고 그동안 두 이름이 공존하므로 값보다 위험이 컸다. 대신 그 표가 무엇을 담는지를 COMMENT 에 정본 이름으로 적고 대응표에도 남겼다.
검증 — 문서 머리말과 화면 이름
문서 맨 위에 그 문서에서 쓰는 이름을 적었다.
# 결제 연동
> 이 문서는 **결제(payment)** 를 다룬다.
> 관련 표기: PG, 페이먼트, 결제 게이트웨이검색하면 이 줄이 걸린다. 어느 표현으로 찾아도 이 문서에 닿으므로 간단한데 효과가 컸다.
문서만이 아니라 대화에서도 이름이 달랐다. 같은 화면을 두 사람이 주문 목록과 주문 관리로 다르게 불렀다.
화면 제목은 주문 관리인데 admin_menu 에는 주문 목록으로 돼 있어서 둘 다 맞는 셈이었다. 화면 제목과 메뉴 이름을 맞췄고 이것은 UPDATE 한 줄이라 위험이 거의 없으면서 쓰는 사람이 바로 체감한다.
쉬운 것부터 맞추니 이야기가 통하기 시작했다.
정리
- 같은 것을 여러 이름으로 부르면
grep으로 못 찾는다 - 나머지가 있다는 것 자체를 모르게 된다
- 시기마다 다른 사람이 만들면 자연스럽게 그렇게 된다
- 한국어와 영어가 섞이면 더 갈린다
- 전부 바꾸는 대신 별칭 대응표를 만든다
- 대응표에 코드 폴더와 테이블과 설정 키와 화면을 같이 적는다
- 새로 만드는 것부터 이름을 통일한다
- 옛 이름은 어차피 크게 고칠 때 같이 바꾼다
- 테이블 이름은 위험이 커서 대개 남기고
COMMENT에 정본을 적는다 - 문서 맨 위에 관련 표기를 적으면 어느 말로 찾아도 걸린다
- 화면 제목과 메뉴 이름이 다른 것부터 맞춘다