코드 작성·변경 원칙과 모듈화

#네 가지 원칙

시험 — 바뀐 모든 줄이 요청으로 곧장 이어지는가? 아니라면 범위를 벗어난 변경입니다.

내가 바꾼 결과로 쓰이지 않게 된 import·변수·함수는 지웁니다. 원래 있던 죽은 코드는 요청이 없으면 그대로 둡니다.

#파일 크기와 모듈화

• 분리할 때 순환 참조가 생기지 않게 합니다.
• 분리 기준은 "줄 수"가 아니라 책임입니다. 한 파일이 한 가지 일을 하게 나눕니다.

왜 — 한 파일에 여러 기능이 섞이면, 한 기능을 고칠 때 다른 기능이 깨지는지 알기 어렵고 로그·리뷰도 파일 단위로 나눌 수 없게 됩니다.

#단일 출처(Single Source of Truth)

같은 값·같은 이름표를 여러 곳에서 쓰면 한 곳에만 정의하고 나머지는 그것을 읽습니다.

• 서버와 화면이 같은 상태 이름을 쓰면, 양쪽의 정의 파일을 함께 갱신합니다.
• 로그 경로, 알림 수신처, 표시명 같은 것은 정해진 한 모듈을 통해서만 만듭니다.

#서버와 화면은 함께 확인한다

서버나 화면(클라이언트) 어느 한쪽을 고칠 때, 양쪽이 같은 동작을 하는지 함께 확인합니다.

• 서버의 판정 조건을 바꾸면 → 화면의 표시·판정도 확인
• 화면의 표시 규칙을 바꾸면 → 서버가 그 상태를 실제로 만들어 내는지 확인

수정 후 "서버가 이 상태를 만들고, 화면이 그 상태를 이렇게 표시한다"를 한 문장으로 설명할 수 있어야 합니다. 설명이 안 되면 아직 한쪽만 본 것입니다.

#조용히 다른 값으로 바꿔치지 않는다

값을 못 읽었을 때 그럴듯한 다른 값으로 채우지 않습니다. 없으면 없다고 경고합니다.

// X — DB에서 수신처를 못 읽으면 관리자 번호로 대체
const to = readOwnerPhone() || ADMIN_PHONE;   // 로그엔 "보냄", 실제 수신자는 엉뚱한 곳

// O — 못 읽으면 빈 값 + 1회 경고
const to = readOwnerPhone();
if (!to) warnOnce('수신처 없음 — 호출 위치: ' + caller);

왜 — 실제 사례로, 고객에게 가야 할 알림이 관리자에게만 갔는데 로그에는 "발송함"으로 남아 몇 번이나 원인을 놓쳤습니다. 안 보낸 것보다 나쁩니다.

부팅 시점에 한 번만 값을 읽어 고정해 버리는 코드(예: getter 를 구조분해로 받기)도 같은 함정을 만듭니다. 매번 읽어야 하는 값은 매번 읽습니다.

#수정 이력은 소스가 아니라 이력 파일에

• 소스·문서 안에 ## 수정 이력 블록을 새로 넣지 않습니다.
• 파일 상단에는 그 파일의 역할 설명만 둡니다.
• 작업 이력은 저장소의 이력 파일(예: history.md)과 커밋 메시지에 남깁니다.
• 기존 수정 이력 블록은 일괄 제거하지 않고, 그 파일을 실제로 고칠 때 함께 지웁니다.

이력 파일 한 줄 형식:

**2026-10-27 14:05:12** 예약세척 시작 전 취소 시 우유밀기 차단이 걸리던 판정 수정

• 날짜만이 아니라 시분초까지 적습니다.
• 라벨·스타일 등 화면 표시만 바뀐 작업은 기록하지 않습니다. 로직 변경만 기록합니다.

왜 — 파일마다 이력을 붙이면 금방 낡고, 같은 내용이 커밋 기록과 중복됩니다. 이력은 한곳에서 시간순으로 보는 편이 쓸모 있습니다.

#설계를 먼저 갱신하고 구현한다

의미 있는 기능 추가·동작 변경·통신 명령 추가는 설계 기록(명령 표·조건·순서)을 먼저 갱신한 뒤, 그 기준으로 구현합니다. 설계 기록 없이 명령·게이트·주기 조회 로직만 추가하지 않습니다.