코드 설명은 단순하게 유지해 주세요

• 코드 리뷰에서 긴 설명과 큰 diff가 함께 오면 검토자가 핵심인 변경 이유를 파악하기 어려우므로, 커밋 메시지·머지 리퀘스트 설명·주석은 간결해야 함
• 설명은 무엇이 바뀌었는지보다 왜 바뀌었는지에 집중해야 하며, 많은 변경 내용은 코드 자체로 확인 가능함
• 모든 맥락을 한 번에 담으려는 긴 설명은 일부 검토자의 집중과 리뷰 속도를 떨어뜨릴 수 있음
• 머지 리뷰에서는 원자적 커밋이 특히 중요하며, 작은 수정은 git amend, 병합 전 정리는 rebase나 squash로 처리할 수 있음
• LLM 도구를 쓰더라도 주석·설명·커밋 메시지는 직접 작성하는 편이 코드 이해와 리뷰 접근성에 더 도움이 됨

---

리뷰 설명은 “무엇”보다 “왜”에 집중

• 코드 리뷰에서 설명, 커밋, 머지 리퀘스트가 과도한 정보로 가득 차면 검토 부담이 커짐
• 변경 내용을 길게 나열하기보다, 핵심은 왜 변경했는지를 분명히 쓰는 것임
• 코드 자체가 대부분의 변경 내용을 보여줄 수 있고, 부족한 맥락은 리뷰어가 질문할 수 있음
• 긴 글처럼 작성된 설명은 집중하기 어려운 사람에게 리뷰를 더 느리게 만들 수 있음
• 커밋 메시지, 머지 리퀘스트 설명, 코드 주석은 명확하고 요점 중심으로 필요한 정보만 담는 편이 좋음

커밋 정리와 LLM 사용에 대한 요청

• 커밋은 머지 리뷰에서 특히 원자적이어야 하며, 각 변경은 독립적으로 이해될 수 있어야 함
• 작은 수정은 git amend로 반영하고, 병합 전에는 rebase로 정리하거나 squash할 수 있음
• LLM 도구를 사용하더라도 주석, 설명, 커밋 메시지는 직접 작성하는 편이 낫다고 봄
  • 직접 쓰는 과정이 변경 내용을 이해하는 데 도움이 됨
  • 직접 작성한 설명이 리뷰어에게 더 접근하기 쉬울 수 있음
• LLM 도구는 가능하면 피하는 편이 낫다는 개인적 의견도 함께 담겨 있음
• 접근성이라는 표현에 대한 반응이 있었지만, 핵심은 코드 리뷰 설명을 더 간결하고 검토하기 쉽게 만들자는 요청임

[GN⁺]

Lobste.rs 의견들

• 접근성 요구를 특정 개인 취향과 쉽게 동일시하면 조심해야 함
  ADHD가 있다고 해서 긴 커밋 메시지를 싫어하는 게 보편적 ADHD 특성이라고 보긴 어렵고, 접근성은 “ADHD가 있는 사람이 좋아하는 대로 다 해주기”가 아니라 일반 사용자에게 과도한 부담을 주지 않는 합리적 조정에 가까움
  그래서 고대비, 모션 줄이기, 다크 모드처럼 개인이 선택할 수 있는 설정 뒤에 접근성 기능이 많이 놓임

  • 더 명확히 쓸 수 있었겠지만, 내 AuDHD는 제대로 일하고 기능하기 위해 특정 조건을 필요로 함
    긴 텍스트 덩어리, 예컨대 작은 변경에 A4 두 장 분량 설명이 붙는 경우는 일을 완전히 막아버릴 수 있고, 억지로 읽어내면 번아웃으로 이어짐
    “이건 내 접근성 요구이고, 비슷한 사람이 많다는 걸 안다” 정도로 표현해야 할 것 같음
    그래도 요구가 아니라 취향으로 볼 수도 있겠지만, LLM이 만든 텍스트 벽을 커밋 메시지에 붙일 때 나 같은 사람도 염두에 둬 달라는 부탁임
  • 사람마다 다르지만, “요점부터 말해 달라”는 건 꽤 ADHD의 핵심 특성 중 하나라고 봄
    접근성 측면에서도 모두가 이 조정의 혜택을 받는데 굳이 반대할 이유가 없어 보임
  • 내 경험상 신경다양인과 장애인이 겪는 불필요한 어려움 상당수는 접근성 요구를 취향으로 치부하는 데서 생김
    접근성이 높아지면 동등한 출발선에 서기 위해 그 기능이 꼭 필요하지 않은 사람도 함께 이득을 보니, 그 방향으로 가는 건 좋지 않음

• AI 이전부터 늘 지나치게 자세한 주석을 선호했고, 같이 일한 사람들 중에는 놀라는 사람도 많았음
  예를 들면 이 메서드가 있음: https://github.com/ghostty-org/ghostty/…
  지난 15년 동안 언어와 상관없이 대체로 이런 스타일로 써 왔고, AI 시대에는 이 방식을 AGENTS.md에도 명시함
  링크한 파일과 주석은 전부 사람이 쓴 것이고 AI는 전혀 쓰지 않음
  이유는 단순한데, 주석과 코드가 서로 맞아야 하는 이중 기입 규칙을 강제하기 때문임
  둘이 맞지 않으면 주석이 틀렸거나 코드가 틀렸거나 둘 다 틀린 것이고, “둘 중 뭐가 맞지?”라고 묻는 것만으로 많은 문제를 잡아냈음
  결국 자기 프로젝트라면 각자 원하는 방식으로 주석을 달면 된다고 봄

  • 나도 가끔 코드보다 주석을 더 많이 쓴다는 친근한 농담을 듣는데, 이런 주석을 정말 좋아함
    나중에 코드를 다시 읽을 때 당시 내린 국소적 결정의 맥락을 보존해 주고, 리뷰어나 처음 보는 사람이 맥락을 쌓는 데도 도움 됨
    이런 주석은 장황하긴 해도 글에서 말하는 “불필요한 세부사항”은 아니며, 공유한 예시는 “무엇이 아니라 왜를 설명하라”는 격언의 좋은 예로 보임
  • 이런 주석은 훌륭함
    예시처럼 macOS 사용자가 ~/.bash_profile에 셸 설정을 넣고 로그인 셸을 기대하게 된 이유를 설명하는 주석은 특정 결정을 왜 했는지에 대한 유용한 맥락을 제공함
    다만 LLM으로 돌아오면, 아직 개인적으로 그런 품질의 LLM 생성 주석은 본 적이 없음
    보통은 foo()를 한다, 다음에 bar()를 한다, 마지막으로 baz를 한다처럼 코드만 읽어도 명백한 내용을 반복하는 수준에 그침
  • 링크한 유형의 주석은 문제없음
    문제는 아주 작은 변경에도 거대한 표와 글머리표 목록을 붙이는 난장판임
  • 그 정도 상세함은 정말 고맙지만, 개인적으로는 주석보다는 그 메서드를 추가한 커밋의 커밋 메시지에 들어가는 편을 더 선호함
    커밋 메시지는 코드와 항상 같은 시점의 기록으로 남지만, 주석은 시간이 지나며 어긋날 수 있다고 느낌
  • 1467행에서 시작하는 주석은 걸작이고, 피로감이 그대로 느껴짐

• 직장에서 PR 템플릿에 “이 변경의 동기와 리뷰에서 살펴봐야 할 중요한 설계 결정을 직접 설명해 달라”고 정중히 적어 봤음
  그런데 10번 중 9번은 그때그때 쓰는 LLM이 템플릿 전체를 날려버리고, 추가한 테스트 수와 통과 체크박스, 사소한 내용의 긴 곁가지를 포함한 장문의 설명을 뱉어냄
  덕분에 리뷰가 아주 즐거워짐

  • 직장에서도 같은 문제가 있음
    누가 LLM 생성 커밋 메시지 도구를 여기저기 넣는 게 좋은 생각이라고 봤는지는 모르겠지만, 결국 커밋 안에서 https://noslopgrenade.com/ 문제가 생김
    커밋 메시지나 풀 리퀘스트 설명에는 변경 동기, 설계 결정, 근거 같은 유용한 맥락이 없고, 코드만 읽어도 알 수 있는 세부 구현을 문단으로 풀어쓴 내용으로 변질됨
  • 나도 같은 동작을 봤음
    agents.md에 “커밋 메시지를 작성할 때는 commit-messages.md를 참고하라”고 추가하는 방안을 생각 중임
    commit-messages.md에는 통과/실패 테스트 체크박스 금지, 개별 테스트 나열 대신 요약하거나 아예 쓰지 않기 같은 커밋 메시지 지침을 넣으면 될 듯함

• 내가 무엇을 하는지 주석으로 쓰는 때는 왜 하는지가 아니라, 그 방식이 맞는지 확신이 없을 때뿐임
  반복적으로 고통을 주는 대표 원인은 정규식임

  • 나도 같음
    모든 것을 탄탄히 설명해야 하는 때도 있지만, 요즘은 변수명 변경 같은 작은 변경에도 거대한 설명이 붙는 걸 봄

• 흥미롭게도, 나는 오히려 커밋 메시지가 너무 짧다는 얘기를 많이 들어왔음

  • 이 글의 논의는 반대 방향, 즉 설명이 너무 짧다고 불평하는 Chesterton middle finger 글과 나란히 놓임
  • 너무 짧을 수도 있지만, 거기에 소설 한 편을 넣는 것도 말이 안 됨
  • LLM은 정말 너무 많이 씀
    그래서 claude가 주석을 절대 쓰지 않도록 설정했는데, 내가 수동으로 98%를 지우고 남은 2%도 다시 쓰고 있었기 때문임

• 보통 매우 설명적인 커밋 메시지를 좋아하지만, 뉴스 기사형 구조처럼 가장 중요한 정보를 먼저 두고 덜 중요하지만 여전히 관련 있는 세부사항을 뒤에 배치하는 편임
  예를 들면 제목에는 가장 중요한 정보를 최대한 밀도 있게 담고, 첫 문단에는 변경 내용을 덜 압축된 문장으로 설명하고, 뒤 문단에는 코드 변경의 성격을 정말 이해하기 어렵지 않으면 자세히 읽을 필요 없는 추가 세부사항을 둠
  커밋 메시지가 훗날 코드를 읽는 사람에게 얼마나 중요한지 과소평가되는 것 같음
  코드베이스를 파다가 어떤 블록이 왜 저렇게 생겼는지 궁금할 때, git blame이 어설퍼 보이는 접근이 사실 더 좋아 보였지만 불완전했던 여러 접근 끝에 남은 선택이었다는 걸 지독히 자세히 설명한 커밋 메시지로 이어지면 실망한 적이 없음
  글쓴이의 요지로 돌아가면, 커뮤니케이션에 명시적 표지를 넣는 건 좋은 조정이고 일반적으로도 유용함
  커밋 메시지 중간에 “이 코드를 리뷰하는 중이라면 여기서 읽기를 멈춰도 된다” 같은 문장을 넣을 수 있음

• “불필요한 세부사항은 필요하면 물어보면 된다”는 말은 그 사람이 계속 곁에 있을 거라고 과감하게 가정하는 것임
  10년 넘은 FLOSS 코드베이스에 기여하기 시작하면서 커밋 메시지를 열심히 쓰기 시작했음
  왜 코드가 그렇게 존재하는지 더 알아내는 유일한 방법은 git 고고학이었고, Emacs의 vc-annonate를 익혀 쉽게 추적하게 됨
  직장 코드에서도 내가 유지보수하는 코드베이스의 원 작성자가 이미 오래전에 떠난 경우가 여러 번 있었음
  커밋 메시지는 리뷰 중에만 읽히는 게 아니고, 사실 많은 리뷰 UI는 커밋 메시지를 숨김
  문제는 장문의 커밋 메시지 자체가 아니라 잘못 쓴 커밋 메시지에 가까워 보임
  “커밋 메시지, 병합 요청 설명, 코드 주석은 명확하고 요점을 향해 필요 기반으로 쓰고, 무엇이 아니라 왜를 설명하라”는 지침은 좋아 보임
  이전에 Fix Bugz 🚀️라고만 쓰던 사람이 이제 “모범 사례”를 따르겠다며 LLM으로 커밋 메시지를 쓰는 게 문제일 수도 있음
  내 가설은 대부분의 사람이 커밋 메시지를 쓰지 않는 이유가 읽지 않기 때문이고, 읽지 않는 이유는 GitHub 웹 인터페이스 같은 곳에 의존해 커밋을 둘러보느라 찾아보는 활성화 에너지가 높기 때문임

  • “불필요한 세부사항은 필요하면 물어보면 된다”는 건 리뷰 중의 이야기임
    정보가 중요하다면 주석으로 남기거나 커밋 메시지에 추가할 수 있음
    KDE는 몇 년 전부터 Gitlab을 쓰고 있음

• 장기적으로 후대와 성공적인 git 고고학을 위해서는 균형이 필요함
  인력 변화나 맥락이 머릿속에서 사라지는 일 때문에 나중에 그 불필요해 보이던 세부사항을 물어볼 수 없을 때가 많음
  그 맥락을 기록하기 가장 좋은 시점은 아직 갖고 있을 때임
  정말 원하는 건 중요한 세부사항을 먼저 두고, 개요처럼 명확히 구분하는 방식일 수 있음

• PR이나 코드 설명은 무엇을 했는지가 아니라 왜 했는지를 위한 것임
  코드가 왜 이런 모양인지와 그 뒤의 이유를 말해 줘야 함
  이는 리뷰에도 좋고, 나중에 git 기록에서 코드가 왜 그렇게 생겼는지 찾는 데도 좋음

• 코드 설명을 단순하게 유지하는 건 중요함
  이해하거나 집중할 수 없는 것은 읽을 수 없기 때문임
  동시에 소프트웨어를 개발하다 보면 많은 맥락이 사라지고, 지금은 그 맥락이 작성자와 이야기해 본 사람, 또는 코드를 깊게 본 사람의 머릿속에만 있음
  하지만 그 맥락은 코드와 더 많이 엮여야 하지, 덜 엮이면 안 된다고 봄
  작성자와 항상 이야기할 수는 없으니, 언제나 접근할 수 있고 코드와 함께 갱신되는 곳에 적어둬야 함
  현재 대부분의 개발 흐름에서 그에 가장 적합한 장소는 git 커밋 메시지임
  맨 위에 요약을 쓰는 건 좋지만, 코드 변경에 대한 추가 설명도 남기길 권함
  지금은 중요하지 않아 보이는 내용까지 맥락을 밖으로 꺼내 두면 미래의 내가 고마워할 것임
  앞으로는 그런 맥락을 커밋 메시지에만 넣는 방식보다 더 나은 접근이 필요하고, 그래서 개인적으로는 코드의 “무엇”과 “왜”를 설명할 공간을 더 주는 문학적 프로그래밍을 좋아함