4 posts
Literate programming은 Markdown 파일을 single source of truth로 삼아 문서, 테스트, 구현체를 동기화 상태로 유지한다. Python 30줄로 구현하는 방법을 소개한다.
당신의 문서, 테스트, 코드는 동일한 이야기를 제대로 전달하지 못하는 세 개의 파일이다. 소스의 함수 시그니처를 업데이트한다. README 예제를 잊는다. 일주일 후, 신입 사원이 오래된 스니펫을 프로덕션에 복사한다. 테스트 파일은 여전히 예전 동작을 예상 결과로 인코딩하고 있다.…
LLM 대화에는 의도, 거부된 대안, 그리고 작동하는 코드가 담겨 있습니다. 이것이 바로 문서가 되어야 할 것입니다. 다음은 일회성 채팅을 내러티브를 잃지 않고 지속 가능하고 검색 가능한 문서로 전환하는 방법입니다.
당신은 Claude와 45분을 들여 재시도 회로를 설계했다. 실패 모드를 설명하고, 계단식 압력을 숨기기 때문에 지수 백오프를 거부한 뒤, jitter가 포함된 token-bucket rate limiting으로 결정하고 작동하는 구현을 생성했다. 설명은 명확했고, 추론은 타당했으며,…
Literate programming은 코드를 먼저 인간을 위해, 그 다음 기계를 위해 작성해야 한다고 약속했다. 40년이 지난 지금, 거의 아무도 그렇게 쓰지 않는다. 소프트웨어 문서화에서 가장 우아한 아이디어가 우리의 작업 방식을 바꾸지 못한 이유는 다음과 같다.
1984년, Donald Knuth는 급진적인 전환을 제안하는 논문을 발표했다. 프로그램은 컴파일러를 위해 작성되고 인간을 위해 주석을 다는 것이 아니라, 인간을 위한 문학으로 작성되어야 하며, 컴파일러는 그로부터 실행 가능한 부분을 추출해야 한다. 그는 이를 literate…
아키텍처 문서는 저장하는 순간부터 썩기 시작한다. 코드로부터 다이어그램을 생성하고, ADR을 남기며, 자동화된 아키텍처 테스트로 문서를 정직하게 유지하는 방법을 알아본다.
위키에서 본 모든 아키텍처 다이어그램은 틀렸다. 극적으로 틀린 건 아니다. 조용히, 점진적으로 틀린 것이다. "Auth"라고 적힌 서비스는 6개월 전에 세 개의 microservice로 쪼개졌다. "sync call"이라고 표시된 화살표는 이제 queue를 통해 async로 동작한다.…