주석의 예상 독자

컴퓨터 과학자로 구성된 팀 내 단 한 명의 생물학자라면 어떨까요?
그렇다면 당연해 보이는 내용이더라도 코드를 생물학적 맥락으로 설명하는 것이 좋습니다.
요점은 다른 사람의 관점에서 생각하고 예상되는 질문을 선제적으로 언급하려고 노력하는 것입니다.

다른 사람의 관점에서 생각하고 예상하는 질문을 선제적으로 언급 해야 한다는 말에 깊이 공감하지만, 한편으로 켄트 벡은 주석의 예상 독자를 매우 광범위하게 설정하고 있다고 느꼈습니다. 실무에서 주석의 예상 독자는 동료 개발자로 한정하는 것이 보다 현실적이라고 생각 했습니다.

테스트 코드의 display name

테스트 코드의 diaplay name 을 설명하는 주석의 한 형태로 볼 수 있다고 생각 했습니다. 코드를 직접 작성하지 않는 사람에게도 서비스에 대한 유용한 정보를 제공할 수 있기 때문입니다.

선언적 주석을 사용한 프로그래밍

GitHub Copilot이나 Cursor IDE 같은 도구들을 보았을 때, 주석만으로 의도를 표현하고 AI가 그에 맞는 코드를 생성하는 방식의 개발이 현실화 될 수 있겠다고 생각 했습니다. 선언적 프로그래밍 방식은 ‘어떻게 해야 하는지’ 가 아닌 ‘무엇을 해야 하는지’ 결과에 중점을 둔 패러다임 입니다. 주석을 어떻게 작성 하느냐에 따라 AI 가 작성해주는 코드가 달라지겠지만, 선언적으로 작성 된 주석 만으로도 애플리케이션 개발이 가능하겠다고 생각 했습니다.

주석도 코딩이다

실무에서 당연하게 수행하는 것들을 켄트 백이 말해주는 느낌을 받았습니다.

코드를 읽기를 시도하며 의도를 이해하려고 시도하다가 이해가 되는 순간 다음의 나를 위해 표현력을 높이려는 시도를 합니다.

하나의 방법은 의미있는 개념으로 코드를 개념화 하는 것이구요. (EX. PolPod 클래스 추출)

다른 하나의 방법은 이해한 내용을 주석으로 남기는 것입니다. 상황에 따라 인라인 주석이나 함수 수준으로 남기는 편입니다.

마지막으로 의존성을 주석으로 표현하는 말에도 공감을 했습니다.

코드를 읽다보면 보이는 코드상 의존성들을 바로 제거하면 좋지만 작업을 분리하고자 할 때에는 주석으로나마 의존성들을 기록해두는 편입니다.

저도 처음 보는 코드, 옛날 코드를 볼 때 주석의 도움을 많이 받습니다.
복잡한 프로그램언어 사이에서 한글로 작성된 주석은 가뭄의 단비같습니다.
다만 주석의 단점은, “가짜뉴스“를 만들 수 있다는 것입니다.
분명 대부분의 사람들은 주석이 있다면 주석을 보고 이해할텐데, 코드는 변화하였지만 주석은 따라가지 못한다면?

예전 팀에서 주석에 대한 이야기가 나왔고, 어떤 분은 ‘주석을 작성하는 것‘을 들이려면, 코드가 변경될 때 해당하는 주석도 함께 같이 변경이 되어야만 하는 규칙을 만드는건 어떠냐고 하셨습니다.
공감되는 제안이었으나 시스템적으로 강제할 수 없다는 것이 아쉬운 점이었습니다.

코드가 아무리 명쾌 하더라도

코드가 아무리 명쾌 하더라도, 혹은 오히려 명쾌하기 때문에 표현할 수 없는 것들이 있습니다.

• 핵심 매커니즘일 경우, 왜 이런 매커니즘이 선택 되었는지
• 이 API를 구현할 때 지켜야할 규칙은 무엇인지
• 이 클래스의 의도된 역할은 무엇이고 어떤 방향으로 확장하려 하는지

위의 예시 들은 코드로 표현될 여지가 전혀 없는 것들입니다. 이런것들은 명백히 주석화 되어야 한다고 생각합니다.
그리고 이런 종류들은 코드의 진화에서 비롯 되는 주석과의 불일치도 잘 없는 것 같습니다.
(진화 자체가 잘 안일어나니)

하지만 좋은 코드를 통해 드러날 수 있는 내용들은 주석이 아니라 코드가 강하게 지향 되어야 한다고 생각합니다.

개인적인 경험에서 주석과 테스트 코드이 유지 보수는 굉장히 등한시 되는 경우들을 많이 보아왔습니다.
테스트 코드의 변경은 assert만 수정 되어 given/when/then에서 드러나는 문맥은 실제 코드와 어긋나 버렸고,
주석은 회색 폰트로 누군가 적어둔 자신과는 상관 없는 무언가에 그쳤습니다.

이런 상황에서 주석으로 문제를 풀고자 하는 시도가 올바른지 아직도 모르겠습니다.

어쩌면 ‘주석을 잘 적어서 이해의 난도를 낮추자’라는 전략은 주석 또한 코드이 일부이며 설계라는 사고를 갖춘 곳에서 유의미한 전략일 것 같습니다.

외국인이나 장님 혹은 어린이

자신이 이 코드를 처음 읽는 사람이라고 가정해 보세요.

제럴드 와인버그의 책 <대체 뭐가 문제야>에서 문제를 바라보는 새로운 관점으로
문제 정의가 적절한가를 확인하는 질문이 떠오릅니다.

여러분이 내린 정의에 대해 외국인이나 장님 혹은 어린이를 통해서 검증하라. 혹은 여러분 자신이 외국인, 장님 혹은 어린이가 되어 보라.

하지만 내가 직접 만드는 코드는 '이 코드를 처음 읽는 사람' 처럼 코드를 보기는 어렵습니다. 켄트 벡은 실용적인 아이디어를 제안합니다. 과거의 나를 메타 인지 하는 것이죠.

15분 전의 자신을 떠올려 보세요.

주석에 '왜'를 써 가치 더하기

Java doc에 빠져 있을 때가 있었습니다.
이클립스를 쓰던 시절 단축키를 누르면 메소드에 Java doc이 포멧을 자동으로 만들어지고
설명을 채우면 HTML로 만들어지니 이것이 다른 사람에게 도움이 될 것이라 믿었습니다.
하지만 시간 투자 대비 얻는 것(ROI)이 매우 적더군요.
생각해 보니 무의식적으로 '무엇'을 하는지 쓰는 것에 치중하고 있었습니다.

저는 코드를 처음 볼때에는 궁금하는 것은 행위가 아닙니다.
행위는 코드를 분석하면서 자연스럽게 머릿 속에 그려집니다.
가장 궁금한 것은 "왜 이렇게 하는거지?" 입니다.

'다음은 네트워크 호출 횟수를 최대한 줄여야 하므로 다소 복잡해졌습니다.'

켄트 벡의 예시는 왜 코드를 이렇게 만들었는지 설명해 주는 좋은 예시라고 생각합니다.

날마다 조금씩 나아지기

그 때까지는 주석을 달아서 결합도 문제를 미리 지적해 두는 것이, 모래 속에 묻듯 그냥 두는 것보다 훨씬 나을 것입니다.

외부 문서 주석

너무 복잡한 내용은 주석으로 설명하기도 어려울 것입니다.
특히 비즈니스 도메인에 대한 내용은 너무 방대하기 때문에 주석으로 설명하기 쉽지 않습니다.
이럴때 외부 문서 링크를 주석으로 등록해두는 경우가 종종 있는 것 같습니다.

이런 문서는 지엽적인 이슈에 관련한 문서와 다르게 하나의 문서를 계속 업데이트 해가는 경우가 많습니다.
(지엽적인 이슈는 이슈마다 문서를 새로 만들고 처리)

이런 특징들 때문에, 처음에는 이런 처리가 잘 동작하는 것 처럼 보이나
계속 서비스를 발전 시켜 나가다 보면 링크된 문서의 내용과 코드가 달라지는 경우가 많은 것 같습니다.
문서가 먼저 발전해서 코드가 뒤쳐진다거나 (작은 이슈), 코드만 발전해서 문서가 뒤쳐지는 경우(큰 이슈)를 봐온 것 같습니다.
(모든 요구사항이 비즈니스 도메인에 관한 문서를 업데이트 하는건 아니고, 별도의 문서를 통해 요청 되는 경우도 있기 때문)

결국 문서와 코드의 싱크를 맞추는 작업들이 주기적으로 일어나야 하는데
적절한 주기도 얼마인지 항상 고민됩니다.