요즘 AI가 코드를 뚝딱 만들어내는 시대에, 과연 어떤 코드가 오래 살아남고, 또 사람들에게 제대로 이해될 수
있을까요?
이 질문을 품고, 저는 존 오스터하우트 교수의 이라는 책을 다시 펼쳤습니다.
특히 이번 독서에서는 13장 '주석은 코드에서 명확하지 않은 것을 설명해야 한다'와 14장 '이름 선택하기'에
집중했습니다.
솔직히 말해, 저는 예전에는 주석이나 이름을 '스타일'의 문제로 치부하곤 했습니다.
개인의 취향이나 팀의 가이드라인 정도로 생각했죠.
하지만 이 책은 그런 제 가설을 완전히 뒤흔들었습니다.
이 책은 설계가 거창한 아키텍처 선언이 아니라, 매일 우리가 작성하는 코드의 작은 부분들, 즉 주석과 이름에서
시작된다고 말합니다.
핵심은 이것입니다.
좋은 주석과 좋은 이름은 단순히 기계가 실행할 절차를 적어놓는 것이 아니라, 코드를 읽는 '사람'이 올바른 사고
모델을 갖도록 돕는다는 거죠.
가장 인상 깊었던 조언 중 하나는 '코드 내용을 반복해서 주석으로 달지 말라'는 것이었습니다.
주석은 코드가 '무엇을 하는지'가 아니라, '왜 그렇게 했는지', 혹은 '코드가 숨기고 있는 제약 조건'을 설명해야
한다는 거죠.
반복되는 설명은 유지보수 비용만 늘릴 뿐, 가치를 주지 못한다는 말에 깊이 공감했습니다.
또, 인터페이스 주석은 단순히 사용법을 나열하는 것을 넘어, 사용자가 해당 모듈을 어떻게 이해하고 활용해야 할지
'사고 모델'을 만들어주는 역할을 한다고 합니다.
이름 역시 마찬가지입니다.
저자는 '이름은 짧은 문서이자 작은 추상화'라고 말합니다.
정확하고 명확한 이름은 별도의 설명 없이도 코드의 의도를 전달하고, 모호한 이름은 버그의 온상이 된다는 지적은
너무나 당연하면서도, 늘 놓치기 쉬운 부분이었습니다.
이러한 관점을 제 실무에 적용해보니, 코드 리뷰의 질문이 완전히 달라질 수 있겠다는 생각이 들었습니다.
단순히 '이 코드가 잘 작동하는가?'를 넘어, '다음에 이 코드를 수정할 개발자가 무엇을 알아야 하는가?'로 질문이
바뀌는 거죠.
설계는 특별한 의식이나 회의가 아니라, 매일 우리가 선택하는 이름, 경계, 예외 처리, 주석, 그리고 코드 계층
속에 숨어있다는 것을 다시금 깨닫게 됩니다.
이 책을 덮고 나서, 저는 최근에 제가 수정한 모듈 하나를 다시 열어보았습니다.
주석과 이름이 과연 '코드가 말하지 못하는 의도와 제약'을 잘 담고 있는지, '추상화의 정확도를 높이는 짧은 문서'
역할을 하는지 꼼꼼히 따져보았죠.
미래의 제가, 혹은 동료 개발자가 이 코드를 보았을 때, 어떤 질문을 할지 미리 상상하면서 말입니다.
그리고 한 가지 더, AI 에이전트가 코드를 작성할 때, 이런 '사람을 위한 설계 원칙'을 어떻게 검증 루프에 넣을
수 있을까 하는 질문도 생겼습니다.
단순히 기능 구현을 넘어, '인간 이해도'를 평가하는 기준이 필요하다는 생각으로 이어지더군요.
이 책, 의 7회차 독서 범위는 단순히 코드를 잘 짜는 기술을 넘어섭니다.
코드의 수명이 길어질수록, 협업의 중요성이 커질수록, 더더욱 중요한 '설계 철학'을 고민하는 분들에게 큰 울림을 줄
것 같습니다.
특히 팀의 리드나 시니어 개발자, 혹은 주니어라도 '좋은 코드'의 본질에 대해 깊이 알고 싶은 분이라면 꼭 한번
읽어보시길 권합니다.
결국 좋은 이름과 주석은 코드를 그저 '꾸미는' 문장이 아니라, 독자가 올바른 '모델'을 갖게 하는 강력한 '설계
표면'이라는 것을 다시금 마음에 새깁니다.
다음
독서에서는 또 어떤 질문이 저를 기다리고 있을까요?