코드 설명은 단순하게 유지해 주세요
코드 설명은 단순하게 유지해 주세요
핀란드 KDE 개발자 Akseli(Aks)의 블로그 글과 Lobste.rs 커뮤니티의 토론을 분석한 노트.
1. 원문 핵심 내용
글쓴이와 배경
Akseli(Aks)는 핀란드의 KDE 개발자이자 아마추어 게임/FOSS 개발자다. ADHD와 AuDHD(자폐 스펙트럼 + ADHD)를 가지고 있으며, 이 글은 코드 리뷰 과정에서 반복적으로 겪는 어려움을 바탕으로 작성했다.
핵심 주장
코드 리뷰 시 커밋 메시지, 머지 요청 설명, 코드 주석이 지나치게 길고 불필요한 세부사항으로 가득 차 있다. 특히 "무엇을 바꿨는지"를 장황하게 설명하는 반면, "왜 바꿨는지"라는 핵심 정보는 묻히는 경우가 많다는 것이다.
Aks의 요청은 간단하다:
- 커밋 메시지와 PR 설명은 명확하고, 요점만, 필요할 때만
- "무엇"이 아니라 "왜"를 설명하라
- 코드로 충분히 전달되는 내용은 주석으로 중복하지 말라
- LLM 도구로 생성한 주석/설명을 그대로 붙여넣지 말고, 사람이 직접 작성하라
- 커밋은 원자적(atomic)으로 유지하라 — 하나의 커밋이 독립적으로 의미를 가져야 함
접근성 관점
Aks는 이 문제를 "접근성(accessibility)" 관점에서 제기한다. ADHD 뇌는 긴 텍스트 블록을 처리하는 데 어려움을 겪으며, 지나치게 장황한 설명은 코드 리뷰 속도를 늦출 뿐만 아니라 번아웃(burnout)으로 이어질 수 있다는 것이다.
"나는 소설을 읽고 싶지 않아. 보통 짧은 문단은 괜찮아. 불필요한 세부사항은 필요하면 물어보면 돼."
LLM에 대한 우려
Aks는 LLM 도구가 코드 설명의 질을 더 악화시키고 있다고 지적한다. LLM이 생성하는 설명은 종종:
- 코드가 이미 보여주는 내용을 반복하는 "무엇" 설명
- 지나치게 장황하고 중복된 내용
- 실제 맥락이나 의도를 전달하지 않는 형식적인 텍스트
원자적 커밋
커밋은 가능한 한 작고 독립적으로 유지해야 한다. git amend를 활용해 작은 수정을 통합하고, 머지 전 rebase로 정리하거나 squash하는 것을 권장한다.
2. 커뮤니티 반응 (Lobste.rs)
HN 게시는 없었으나, Lobste.rs에서 활발한 토론이 있었다. 주요 논점들을 10개 세부 항목으로 정리한다.
2.1 접근성 vs 개인 취향 — hyperpape vs Aks
주장: hyperpape는 "ADHD가 있다고 해서 긴 커밋 메시지를 싫어하는 것이 보편적 ADHD 특성은 아니다. 접근성은 'ADHD가 있는 사람이 좋아하는 대로 다 해주기'가 아니라, 일반 사용자에게 과도한 부담을 주지 않는 합리적 조정(rational accommodation)이다"라고 비판했다.
근거: 접근성 기술(고대비, 모션 줄이기, 다크 모드 등)은 대부분 개인이 선택할 수 있는 설정 뒤에 놓인다. 특정 개인의 선호를 보편적 필요로 동일시하면 오히려 다른 접근성 요구를 간과할 수 있다.
반론: 글쓴이 Aks는 "내 AuDHD는 특정 조건이 있어야 일하고 기능할 수 있는 것이다. 긴 텍스트 블록은 내 작업을 완전히 막을 수 있다"라고 반박했고, JadedBlueEyes는 "접근성 요구를 취향으로 치부하는 것은 장애인에게 불필요한 고통을 준다"고 Aks를 지지했다.
대표 작성자: hyperpape, Aks, JadedBlueEyes
2.2 "이중 기입(double-entry)" 주석 방식 — mitchellh
주장: HashiCorp 창업자 Mitchell Hashimoto(mitchellh)는 오히려 지나치게 자세한 주석을 선호한다고 밝혔다. 코드와 주석이 서로를 검증하는 "이중 기입 규칙"을 강제하면, 둘이 일치하지 않을 때 "둘 중 뭐가 틀렸나?"라는 질문으로 많은 버그를 찾을 수 있다.
근거: 15년 이상 이 스타일로 작성해 왔으며, 실제 사례로 Ghostty 프로젝트의 macOS shell 설정 관련 주석을 예시로 들었다. AI 시대에 이 방식을 AGENTS.md에 명시하고 있다.
반론: 이 방식이 모든 프로젝트에 적합한 것은 아니다. mitchellh 자신도 "각자의 프로젝트는 각자의 방식으로 주석을 달면 된다"라고 인정했다.
대표 작성자: mitchellh
2.3 LLM이 PR 템플릿을 무력화하는 현상 — ammar2
주장: 직장에서 PR 템플릿에 "이 변경의 동기와 리뷰에서 살펴봐야 할 중요한 설계 결정을 직접 설명해 달라"고 정중히 적어봤으나, 10번 중 9번은 LLM이 템플릿을 무시하고 "추가한 테스트 수와 통과 체크박스, 사소한 내용의 장문 설명"을 뱉어낸다는 경험담.
근거: LLM은 "동기(motivation)"나 "설계 결정(design decision)"과 같은 추상적 개념을 이해하지 못하고, 대신 코드 변경의 사소한 세부사항을 나열하는 경향이 있다.
반론: 일부 작성자들은 LLM을 도구로 쓰되, 사람이 최종 편집하는 하이브리드 워크플로우를 제안했다.
대표 작성자: ammar2
2.4 "왜" vs "무엇"의 경계 — nemith, liberty
주장: PR이나 코드 설명은 "무엇을 했는지"가 아니라 "왜 했는지"를 위한 것이다. 코드가 왜 이런 모양인지, 그 뒤의 이유와 맥락을 설명해야 한다.
근거: 이는 코드 리뷰에도 좋고, 나중에 git 기록에서 코드가 왜 그렇게 생겼는지 찾을 때도 유용하다. nemith는 "커밋 메시지, 병합 요청 설명, 코드 주석은 명확하고 요점을 향해 필요 기반으로 쓰고, 무엇이 아니라 왜를 설명하라"는 지침을 제안했다.
반론: "왜"만 설명하면 초보 개발자나 새로운 기여자가 코드를 이해하는 데 어려움이 있다는 지적도 있었다. 적절한 균형이 필요하다는 중도적 의견이 다수였다.
대표 작성자: nemith, liberty
2.5 뉴스 기사형 커밋 메시지 구조 — PuercoPop
주장: Facebook의 PuercoPop은 "뉴스 기사형 구조"를 제안했다. 제목에는 가장 중요한 정보를 밀도 있게 담고, 첫 문단에 변경 내용을 덜 압축된 문장으로 설명하며, 뒤 문단에는 정말 이해하기 어렵지 않으면 자세히 읽을 필요 없는 추가 세부사항을 배치한다.
근거: 이 방식은 리뷰어가 원하는 깊이에 따라 읽을 수 있게 한다. "이 코드를 리뷰하는 중이라면 여기서 읽기를 멈춰도 된다" 같은 명시적 표지(signpost)를 중간에 넣으면 더 좋다.
반론: 명시적 표지가 항상 필요한 것은 아니며, 대부분의 리뷰어는 전체를 빠르게 스캔한다는 반론도 있었다.
대표 작성자: PuercoPop
2.6 git 고고학(git archaeology)과 장기적 맥락 — bjeanes
주장: 10년 넘은 FLOSS 코드베이스에 기여하면서 커밋 메시지를 열심히 쓰기 시작했다는 경험담. 왜 코드가 그렇게 존재하는지 알아내는 유일한 방법은 git 고고학이었고, Emacs의 vc-annotate를 익혀 추적을 쉽게 했다.
근거: 직장 코드에서도 자신이 유지보수하는 코드의 원 작성자가 이미 떠난 경우가 많았다. "불필요한 세부사항은 필요하면 물어보면 된다"는 말은 그 사람이 계속 곁에 있을 것이라고 가정하는 것인데, 실제로는 그렇지 않은 경우가 대부분이다.
반론: 모든 프로젝트가 10년 이상 지속되는 것은 아니며, 단기 프로젝트에서는 과도한 문서화가 오히려 부담이 될 수 있다.
대표 작성자: bjeanes
2.7 "잘못 쓴 커밋 메시지"가 진짜 문제 — PuercoPop
주장: 문제가 되는 것은 "장문의 커밋 메시지" 자체가 아니라 "잘못 쓴 커밋 메시지"다. 예전에는 Fix Bugz 🚀 같은 의미 없는 메시지를 쓰던 사람이, "모범 사례"를 따르겠다며 LLM으로 생성한 장문의 의미 없는 텍스트로 바꾼 것이 문제다.
근거: 대부분의 사람이 커밋 메시지를 쓰지 않는 이유는 "읽지 않기 때문"이고, 읽지 않는 이유는 GitHub 웹 인터페이스에서 커밋을 찾아보는 활성화 에너지(activation energy)가 높기 때문이다. 많은 리뷰 UI는 커밋 메시지를 기본적으로 숨긴다.
반론: GitHub의 커밋 메시지 가시성은 개선되고 있으며, git log나 git blame을 직접 사용하는 개발자들은 여전히 커밋 메시지에 의존한다.
대표 작성자: PuercoPop
2.8 문학적 프로그래밍(Literate Programming) — liberty
주장: 커밋 메시지에만 맥락을 넣는 방식보다 더 나은 접근이 필요하며, 코드의 "무엇"과 "왜"를 설명할 공간을 더 주는 문학적 프로그래밍(literate programming)을 좋아한다고 밝혔다.
근거: 문학적 프로그래밍은 Donald Knuth가 제안한 방식으로, 코드를 자연어 설명과 함께 작성하여 프로그램 자체가 문서가 된다. 현재 git 커밋 메시지는 "가장 적합한 장소"이지만, 궁극적으로는 더 나은 도구가 필요하다는 관점.
반론: 문학적 프로그래밍은 실제 개발 워크플로우에 통합하기 어렵고, WebAssembly 등 실행 환경과의 호환성 문제가 있다.
대표 작성자: liberty
2.9 정규식과 "확신이 없을 때" 주석 — mitchellh
주장: "내가 무엇을 하는지 주석으로 쓰는 때는 왜 하는지가 아니라, 그 방식이 맞는지 확신이 없을 때뿐이다"라고 밝혔다. 반복적으로 고통을 주는 대표 원인은 정규식(regular expression)이라고 지적했다.
근거: 정규식은 코드로 읽었을 때 의도가 명확하지 않은 경우가 많아서, 주석으로 의도를 명시하는 것이 특히 유용하다.
반론: 이 의견에는 큰 반론이 없었으며, 대부분의 작성자가 정규식 주석의 중요성에 동의했다.
대표 작성자: mitchellh
2.10 맥락 상실과 기록의 시점 — bjeanes
주장: "정말 원하는 건 중요한 세부사항을 먼저 두고, 개요처럼 명확히 구분하는 방식"이다. 인력 변화나 맥락이 머릿속에서 사라지는 일 때문에, 나중에 그 불필요해 보이던 세부사항을 물어볼 수 없을 때가 많다는 경험담.
근거: "그 맥락을 기록하기 가장 좋은 시점은 아직 갖고 있을 때"라는 통찰. 코드를 작성하고 있는当下에 작성자만이 가진 맥락을 기록하지 않으면, 나중에 그 맥락은 완전히 사라진다.
반론: 모든 맥락을 기록하면 오히려 핵심이 묻힐 수 있다는 우려. 중요도와 우선순위를 구분하는 기준이 필요하다는 의견.
대표 작성자: bjeanes
3. 새로운 시각
3.1 LLM은 "무엇" 설명을 더 악화시키는 촉매제
LLM이 코드 설명을 작성할 때의 근본적 문제는 "무엇 vs 왜"의 구분을 이해하지 못한다는 점이다. LLM은 코드의 동작을 설명하는 데 최적화되어 있지만, 개발자의 의도나 설계 맥락을 파악할 수 없다. 이는 단순히 "LLM을 쓰지 말라"는 주장이 아니라, LLM을 코드 설명에 사용할 때는 반드시 사람이 "왜"를 추가해야 한다는 실용적 교훈을 남긴다.
3.2 접근성 논의의 양극화와 중도적 해결책
Aks의 접근성 주장은 hyperpape의 비판으로 인해 양극화되었지만, 실제로는 두 관점이 모두 타당하다. 해결책은 "모든 사람이 짧은 메시지를 써야 한다"거나 "접근성 요구를 무조건 수용한다"가 아니라, 뉴스 기사형 구조 + 명시적 표지(signpost)와 같은 유연한 방식이다. 리뷰어가 원하는 깊이에 따라 읽을 수 있게 하는 것이 핵심.
3.3 git 고고학은 미래의 코드 리뷰 방식이 될 수 있다
bjeanes의 git 고고학 경험은 중요한 시사점을 남긴다. 현재 코드 리뷰는 "실시간 대화"를 전제로 하지만, 장기적인 코드베이스에서는 작성자가 떠난 후의 리뷰가 더 많다. 커밋 메시지는 "당시의 리뷰어가 아닌, 미래의 개발자를 위한 기록"이라는 관점에서 다시 고려되어야 한다.
4. 자녀/미래 영향
아인, 석현, 은한에게
- 아인: 나중에 프로그래밍을 접하게 된다면, 코드 주석은 "남을 위한 것이 아니라 미래의 나를 위한 것"이라는 점을 알려줘. 특히 정규식 같은 복잡한 로직은 반드시 의도를 주석으로 남기도록 해.
- 석현, 은한: 커밋 메시지를 쓸 때는 "무엇을 했는지"보다 "왜 그 선택을 했는지"를 먼저 생각해 보라고 해. LLM이 만들어준 커밋 메시지를 그대로 붙여넣지 말고, 최소한 "왜"라는 한 줄을 직접 추가하는 습관을 들이게 해.
실용적 조언
- PR 템플릿에 "이 변경의 동기는 무엇인가요?"라는 필수 항목을 넣는다.
- LLM으로 커밋 메시지를 생성하더라도, 반드시 사람이 "왜"를 한 줄 이상 추가한다.
- 뉴스 기사형 구조를 연습한다: 제목 → 핵심 요약 → 상세 설명(선택적).
- 정규식, 복잡한 조건문, 비표준 알고리즘은 반드시 주석으로 의도를 기록한다.