9P by GN⁺ 21시간전 | ★ favorite | 댓글 1개
  • 일부 팀은 모든 TODO 주석을 버그 트래커에 등록하거나, 1년 이상 된 TODO는 자동 삭제하는 정책을 쓰지만, 이러한 관행을 권장하지 않음
  • TODO 주석은 반드시 완수해야만 가치가 있는 것이 아니라, 코드 작성 시점의 맥락·아이디어를 남기는 뇌의 스냅샷 역할
  • 중요한 TODO는 이슈로 관리해야겠지만, 대부분은 우선순위가 낮거나 엣지케이스를 기록하는 메모
  • 잘 배치된 TODO는 미래의 코드 리더가 "이 부분을 리팩터링해도 될까?" 고민할 때 당시 저자의 의도를 파악하는 힌트 제공
  • TODO의 가치는 완수 여부가 아니라, 맥락·의도·가능성을 기록해 미래의 유지보수와 협업에 도움을 주는 점에 있음

TODO 주석, 꼭 처리해야만 할까?

  • 일부 조직에서는 코드 내 모든 TODO를 버그 트래커에 등록하거나, 일정 기간(1년 이상) 지나면 자동 삭제하는 규칙을 적용
  • 그러나 이런 접근은 실제로 비효율적이며, TODO의 본질을 놓침 - 실제로 처리되어야만 가치가 생기는 것은 아님

TODO의 진짜 가치

  • 예를 들어,

    // TODO: 다음 주 출시 전에 이 파일의 뒷부분을 완성해야 함  
    

    같은 주석은 실제로 트래킹할 필요가 있을 수 있음

  • 하지만 좋은 TODO는 대개

    // TODO: 사용자가 이 버튼을 트리플 클릭할 경우, 핸들러에서 \[xyz] 오류 발생  
    

    처럼 엣지케이스를 기록하거나, 지금 당장 하지 못한 구조 개선 아이디어, 놓친 상황 등을 맥락과 함께 기록하는 용도

TODO는 '계획'이 아니라 '창구'

  • 대부분의 TODO는 실제로 즉시 처리될 필요가 없는 낮은 우선순위
  • 작성 시점의 저자의 고민과 판단, 컨텍스트를 미래의 코드 리더에게 전달하는 역할
  • 훗날 코드를 읽는 사람이 "여기 구조를 바꿔도 될까?" 고민할 때, TODO가 당시 저자의 의도를 파악하는 데 도움이 됨

잘 작성된 TODO의 효과

  • 코드 내 TODO는 때로 문제의 여지, 구조 개선 가능성, 미처리된 엣지케이스 등 중요한 힌트를 제공
  • 반드시 해결을 위한 계획이 아니더라도, 협업과 유지보수에서 미묘한 맥락 전달에 큰 역할
  • 결국 TODO 주석은 코드의 이해도와 향후 유지보수성을 높이는 소중한 기록물 역할임

결론

  • TODO는 꼭 완료해야만 가치를 갖는 것이 아니라, 저자의 생각·의도·컨텍스트를 남겨 미래의 코드 리더와의 소통 창구가 됨
Hacker News 의견
  • 나는 "TODO는 항상 구체적인 이슈로 연결되어야 한다"는 입장임
    Merge 전에 TODO를 해결하는 세 가지 방법이 있다고 생각함
    1. 이슈를 남김―실제로 해야 할 일이라면 20초 정도 투자해 기록하고 트래킹하면 좋음
    2. 그냥 바로 처리함―이슈로 만들기엔 너무 사소한 일이라면 커밋 전에 해결하는 것임
    3. 코멘트로 바꿈―고칠 가치도 없고 트래킹할 필요도 없지만 기억하고 싶다면 일반 코드 코멘트로 남기는 걸 추천함
    건강을 생각한다면 브로콜리를 먹듯이 TODO도 트래킹하는 습관이 좋음
    • 외부 시스템에 트래킹하는 건 이슈 등록 뿐만 아니라 분류, 백로그 관리, 재분류, 완료 시 닫기 등 추가적인 수고가 계속 발생함
      외부 시스템에 등록된 이슈는 그 부분 코드를 만지는 개발자들에게 잘 보이지 않을 수 있음
      간단히 고칠 만한 것들도 굳이 트래킹하는 비용이 아깝다면 그냥 TODO로 남기는 것이 효율적임
      코드 내 TODO는 해당 코드 작업 시 한눈에 보이고, 리팩토링할 때도 쉽게 삭제할 수 있음
    • 글 작성자는 기본적으로 3번(그냥 코멘트로 남기기)을 지지하는 것 같음
      하지만 TODO 코멘트와 일반 코멘트의 차이를 명확히 언급하지 않은 점이 아쉬움
      TODO라는 용어 자체가 시각적 강렬함이 있어 어떤 종류의 코멘트인지 바로 알 수 있음
      TODO 코멘트를 굳이 "TO DO(할 일)"로 받아들이지 않아도 된다고 주장하는 건 조금 의심스러운 부분임
      글의 의견엔 대체로 동의하지만, 차라리 그냥 일반 코멘트로 남기는 쪽이 개선이라고 봄
    • "20초 투자해서 기록하고 관리만 하면 된다"고 했는데 그게 바로 TODO 인 셈임
      티켓 시스템에 올린다면 20초보다 오래 걸릴 뿐더러, 도움이 되기보단 오히려 산만함을 유발함
    • 트래킹이 20초면 좋겠지만 (대기업이라) JIRA 티켓 하나 만드는데 필수 입력 항목이 10개 이상임
    • 나는 하나의 규칙만 사용함: 모든 TODO는 반드시 티켓 번호가 들어가야 함
      // TODO: improve the routing https://jira.com/whatever/TIX-1234
      이유는 코멘트가 고아가 되면 아무도 왜 남겼는지 모르게 되기 때문임
      그냥 코멘트만 남기면 추후에 누군가 용도와 배경을 잊어버림
      그러니 반드시 티켓을 만들거나 바로 처리해야 한다고 봄
  • 나는 다음과 같이 구분해서 grep함
    FIXME: 명백하게 잘못되거나 망가진 부분, 최우선
    XXX: 보기 안 좋거나 잘못된 가정이 들어간 부분, 상위 우선순위
    TODO: 언젠가 완전히 새로운 접근 방식/카테고리/분기를 구현해야 하는 부분
    NOTE: 단순한 코멘트보다 더 중요한 정보 전달용
    나는 주로 레거시/유지보수 안 되는 코드 엔진에서 일하고, 여기선 "코드가 진실"이라 JIRA 만들지 않고 읽다 보면서 바로 바로 수정함
    • 나는 다음과 같이 사용함
      TODO: 릴리즈 전까지 꼭 필요한 일, 필수 사항. 만약 해당하지 않으면 다른 카테고리로 옮겨야 함. 릴리즈를 막는 요소임
      FUTURE: 언젠가 TODO가 될 수도 있음, 보통은 구조적 설계 등 선택적 요소임
      MAYDO: 있으면 좋고 없어도 무방
      PERF: 성능이 더 필요할 때 하면 좋음
      그리고 도메인 관련 의미 태그도 사용함
      내 의견은 TODO는 코드 스멜이 아니라, 코드베이스의 핵심적인 부분에 자연스럽게 쌓이는 것임
    • 나는 XXX를 "다음 PR 전에 반드시 고칠 것"이라는 개인적인 메모로 씀
      진지하게 쓰고자 하면 CI에서 해당 문자열이 들어간 코드를 reject하게 설정함
      그런 의미에서 XXX가 내겐 가장 높은 우선순위임
    • 이 스타일이 마음에 듦. 한 프로젝트에서 CI로 FIXME가 포함된 코드는 무조건 reject하고, TODO는 이슈 티켓 없으면 reject하게 했었음
      내려가면서 우선순위를 정하면
      FIXME: 집중을 유지하기 위함. 반드시 해결 후에야 머지 또는 완성되는 코드임
      XXX: 곧 고쳐야 함. 당장은 작동하지만 빠른 시일 내 고쳐야 함
      TODO: 나중에 재방문해야 함. 코드는 완벽하게 사용할 수 있음. XXX보다 낮은 우선순위임
      NOTE: 특이한 점이나 알아야 할 사항을 설명하여 후속 작업자에게 도움을 줌
    • 나도 비슷하게 함. 아직 미완성이고 우회할 수 있는 코드 경로에는 FIXME 대신 assert를 넣음
      TODO는 리팩터링/성능/명확성 개선 같이 가능한 일감을 남기는 용도임
      NOTE는 과거 정보나 당장 보면 알기 힘든 생각의 흐름을 남기는 용도로 씀
    • 이론상 좋지만 이런 약속은 도구 지원 없으면 무의미하다고 생각함
      팀에서 일한다고 가정하면 더더욱 그럴 거임
      그렇다고 멋대로 의미가 없다는 얘기는 아님―이런 도구가 있거나 만들어질 필요가 있다고 봄
  • 완벽함이 선의 적이라는 말이 떠오름
    이런 기술적 부채나 코드 스멜은 사실 더 잘 추적/기록/설명해야 하지만 JIRA처럼 생산성 떨어지는 일을 하자고 하면 오히려 아무 것도 기록하지 않게 됨
    최소한 코드 안에 TODO라도 있으면 어딘가에 남아 있게 됨
    TODO는 실제 "해야 할 일"이기도 하니까 의미 있음
    • 대형 코드베이스라면 여러 사람의 TODO가 뒤섞여 복잡해질 수 있지만, 개인 프로젝트엔 좋은 절충안임
      "더 좋게 할 수 있을 걸 알지만 이를 위해 내 흐름을 일부러 멈추진 않음. 기능이 깨지는 것도 아니고, 있으면 좀 더 좋을 뿐."
      에디터에서 TODO 하이라이트가 간혹 돌아왔을 때 잠깐 해결하고 싶을 때 도움이 됨
      그렇지만 대부분의 TODO는 평생 남아있거나, 실제론 거의 해결되지 않음
    • 가끔 코드에 처리해야 할 신호를 남기고 싶어서 TODO를 남기게 됨
      JIRA, GH Issues 등에 등록해도 궁극적으로는 기록이 연결되어야 함
      그리고 그냥 참조만 남기면 나중에 의미를 잃을 수 있으니, 코멘트에 설명도 함께 있어야 함
    • JIRA 티켓을 AI가 만들어주는 MCP 서버가 Cursor에서 바로 실행되는 기능도 이미 나와 있음
    • git 커밋 메시지에 남기는 게 훨씬 좋다고 생각함
      많은 커밋이 실제로는 내용을 잘 전달하지 못함
      옛날 방식으로 TODO 남기는 대신 더 나은 도구 사용을 장려했으면 함
      많은 개발자가 커밋을 너무 드물게 하고, 한 번에 여러 작업을 한꺼번에 담아버림
      커밋 메시지도 "updating somefile.py" 같이 의미 없는 걸로 올리는 경우가 많음
  • 이건 스타일의 문제임. TODO에 대해 각자 다른 정의나 문화가 있을 수 있음
    내 코드베이스에선 TODO는 여기 설명된 대로 사용됨
    TODO는 구현 설명, 특히 빠진 부분을 문서화하는 용도임―꼭 처리해야 한다는 의미가 아님
    내 생각엔 코드 자체에 실제 할 일 목록을 남기는 건 별 의미가 없음. 우선순위는 계속 바뀌니까, 남길 땐 중요했지만 실제론 아닐 수 있고, 생각 못했던 이슈가 더 나중에 해결해야 할 일이 되기도 함
    TODO 코멘트 갱신만을 위해 PR을 계속 올릴 수는 없는 노릇임
    할 일을 적고 싶다면 이슈 트래커, 혹은 쉽게 업데이트 가능한 텍스트 문서 등 외부에서 관리하는 게 나음
  • 제목이 클릭 유도적이긴 하지만 전체 내용엔 전적으로 동의함
    방금도 #TODO로 극히 드물게 발생하는 예외적 상황을 기록해두었음. 2년째 실제로 발생한 적 없지만, 나중에 내가 왜 이 부분을 처리 안 했는지 궁금할 때 도움이 됨
    이런 건 때론 그냥 코멘트로 남겨야 한다는 분들 말도 이해함. 코드베이스 성격에 따라 다르고, 나처럼 2인 팀 같은 환경에선 TODO 방식이 잘 맞음
    • 우리 팀은 // TBD: [...]를 이런 용도로 썼음. TODO 관련 강박이 있는 사람들이 눈치 못채게 하려고 쓴 꼼수임
  • 분명 가치가 있지만 트래킹할 필요 없는 알려진 이슈를 기록할 공간이 있음이 필요함
    실제로 고칠 계획은 없지만, 나중에 시간이 날 때 혹시 정리할 수 있을지 궁금해져서 한번쯤 ctrl-F로 찾아볼만한 것임
    너무 많은 도구나 프로세스가 TODO를 코드 스멜로 보는 게 불합리하다고 생각함
    • 난 그런 이슈를 실제로 아직 경험해보진 못함
      우선순위 문제일 뿐, 결국 깨진 창(Pragmatic Programmer의 유명 비유)이라고 생각함
      정말 고치지 않기로 한 거라면 소프트웨어 문서에 기록하는 것이 더 나음
  • 글에서 예로 든

    // TODO: If the user triple-clicks this button, the click handler errors because [xyz]
    이건 실제 TODO라기보단 그냥 코멘트에 가깝다고 생각함
    이런 설명형 코멘트는 분명 도움 되지만 TODO라고 하긴 애매함
    TODO는 실제로 해야 할 항목이 분명한, 즉 "이 함수는 XYZ에 따라 다른 값을 반환해야 한다"처럼 바뀌어야 함을 알려주는 것임
    그런 의미에서 TODO는 코드에 묻혀 있을 일이 아니라, 이슈 트래커에 있어야 함
    경험상 TODO는 PR 승인 급한 코드 퀄리티 희생을 정당화하는 방편일 뿐임. 실제로는 거의 실행되지 않으며, “시간 많은 후임 개발자한테 넘기면 언젠가 해결되겠지”란 생각만 남겨둠

    • 코멘트는 왜 이 코드가 이런 식으로 동작하는지 설명하기 위한 것임
      예를 들어 단순히
      // If the user triple-clicks this button, the click handler errors because [xyz]
      이렇게만 쓰면 이게 버그인지, 혹은 원래 의도인지 명확하지 않음
      TODO는 “여기에 완벽하지 않은 부분 있으니 작업할 때 참고해라”라는 간단한 신호
      반드시 해결해야 할 일이라면 다른 곳에 트래킹하는 게 맞음
      하지만 TODO 자체를 줄이다 보면 오히려 미문서화된 코드가 늘어날 뿐이라고 봄
    • 위 예시는 별로 긍정적인 TODO 코멘트라고 생각하지 않음
      그럴 시간에 그냥 해당 버그를 바로 고치거나, 아니면 “트리플 클릭은 [xyz] 때문에 무시됨” 같은 코멘트를 남기면 됨
      트리거와 원인까지 알아낸 상태라면 이미 80%는 작업이 끝난 거라고 생각함
    • 그건 “건너뛰기” 정도로 보면 됨. 아예 작업하지 않아도 괜찮은 경우가 많음
      문제가 되는 건 코드가 완벽히 동작하지 않음에도 그렇다고 가정할 때임
      내가 본 최고의 TODO는 “TODO: encrypt this”처럼 보안 코드에 암호화 안 했다고 명확하게 남긴 것임
      이게 있었기에 코드가 암호화되지 않은 걸 누구나 금방 알 수 있었고, 모듈화로 암호가 따로 처리된 건지, 이중으로 암호화할까 걱정도 줄였음
    • 예시로 든 건 TODO라기보다는 FIXME에 더 가까움
      명확히 오류지만, 그다지 처리할 필요성이 떨어진 경우임
  • 강하게 반대함
    버그로 등록하거나 실제로 작업하지 않을 거라면 TODO를 남기지 말았으면 함
    // TODO: If the user triple-clicks this button, the click handler errors because [xyz]
    이건 현상 기록일 뿐. TODO란 단어는 빼야 맞음
  • 나도 계층적으로 사용함
    FIXME는 꼭 고쳐야 하거나, 다음 단계가 뚜렷이 떠오를 때 사용
    TODO는 그보다 좀 더 뭉뚱그린 생각이나, 그냥 머릿속에서 꺼내 놓고 다음 일에 집중하기 위한 용도임
    아직 아이디어가 덜 무르익었거나, 꼭 해야겠다는 확신이 없거나, 관련된 뭔가를 기다릴 때 등 여러 상황임
    기록하지 않으면 계속 생각나서 머리가 복잡한데, TODO든 뭐든 써 놓기만 하면 심리적으로 훨씬 후련해짐
  • 나는 주석을 코드 작성 능력이 부족하다는 반증으로 봄
    주석 없이 바로 이해될 만큼 코드 쓸 수 있으면 좋겠음
    그래도 나중에 내가 읽어도 못 알아볼 수준으로 헷갈린다면 어쩔 수 없이 코멘트를 쓰고 있음
    슬픈 건 누군가 이후에 코드를 고치면서 주석을 안 바꾸면, 오히려 더 혼란스러워짐
    TODO는 커밋된 코드에 있으면 안 되고, 프로젝트나 이슈 관리 시스템에서 관리해야 맞다고 생각함