이 책이 쓰여진 배경
p14
1. 문제를 이해하려고 시도합니다.
2. 찾아볼 만한 모든 곳에서 기존 해결책을 검색합니다.
3. 운 좋게 해결책을 찾는다면 그 해결책이 효과가 있음을 직접 검증합니다.
4. 찾은 해결책을 운영 환경에 반영합니다.우리는 이것을 '개발자 루프(developer loop)'라고 부르며, 가장 성공적인 프로젝트에는 이러한 각 단계를 따랄 개발자를 안내해 주는 문서가 있습니다.
그렇다면 왜 문서화가 종종 프로젝트 업무 우선순위에서 떨어지거나 완전히 누락되는지에 대한 의문이 생깁니다. ... 우리는 개발자 루프만큼이나 중요한 '문서 작성자 루프(writer loop)'가 있다는 사실을 이해하지 못할 때가 많기 때문입니다.
저는 이 사실을 새로운 개발자가 쿠버네티스를 사용하도록 소개하면서 직접 깨달았습니다.
...
저는 개발자가 필요한 정보를 약 5분 내에 찾지 못하면 프로젝트를 포기하고 다른 프로젝트를 찾아 떠날 수 있음을 곧 알게 되었습니다.
이 부분을 읽으면서, 내가 개발해왔는 순간들을 되돌아 볼 수 있었다. 이 책에서 말하는 것처럼 "개발자 루프" 를 통해서 나는 개발을 한다. 그리고 문서화를 누락한다. 이 책이 쓰여진 이유가 여기서부터 시작된다.
왜 "문서 작성"을 누락하는 것일까? 그리고 누락했을 때, 어떤일이 벌어질까?
책에서는 말한다. 문서 작성을 누락하는 이유는 개발자 루프에 문서 작성은 포함되지 않았기 때문이다. 그 결과 개발자는 그 프로젝트를 하기 싫어한다.(퇴사를 상상하게 될지도 모른다.)
내 경험을 빌리자면, 외주 프로젝트를 인수받는 경우 기분이 유쾌했던 적은 손에 꼽는다. "테스트 코드는 없나요? 이 로직이 버그가 없다는 사실을 제가 직접 UI로 눌러봐야만 알 수 있나요?" 라는 불만을 하거나, "이 코드는 주석처리 되어있는데 무엇인가요?" 그리고 "이 API 문서에 이 객체는 무엇인가요?(아니면 왜 전달해줘야하죠?)" 라는 말을 하게된다. 직접 대면해서 문의하고 이야기하면, 정말 많은 스토리가 있다. 듣기 전까진 비판과 비난을 오가다가, 직접 이야기를 들으면 어쩔 수 없는 요구사항들, 준수해야하는 사항들에 의해서 발생했었고 충분히 이해가 된다.
그런 맥락들이 문서에 조금이라도 녹아있었다면, 외주 진행한 개발자를 이해하기 쉬웠을지 모른다.
클린코드를 잘못 이해했던 과거
p23
'코드 자체로 문서화가 되는거야'.
스스로 했던 말이 뇌리를 스치며 자신을 괴롭힙니다.
...
'코드가 잘 작성되면 그 자체로 문서화가 되는 거야'라는 말을 자주 들어 보았을 것입니다.
...
하지만 일정 규모 이상의 프로젝트는 누군가 개발한 코드의 용도와 사용 방법을 다른 사람들이 빨리 이해할 수 있도록 사람이 읽을 수 있는 형태의 문서가 필요합니다.
개인적으로 코드를 작성을 할 때, 주석이 있으면 흥미롭다. 담벼락에 남겨진 메시지 같다; "우노 여기 왔다감." 융프라옹에 적혀있는 쪽지
그런데, 클린코드에서는 책 초반부에 이런 내용들이 있다.
- "나쁜 코드에 주석을 달지 마라. 새로 짜라", 브라이언 W.커니핸, P.J. 플라우거
- 주석은 필요악이다.
- 주석은 코드로 의도를 표현하지 못해, 실패를 만회하기 위해 작성하는 것이다.
- 주석은 언제나 실패를 의미한다.
- 주석 없이는 자신을 표현할 방법을 찾지 못해 할 수 없이 주석을 사용한다.
- 주석이 오래될수록 코드에서 멀어져 거짓말을 하게 될 가능성이 커딘다.
- 코드는 유지보스를 해도, 주석을 계속 유지보수하기란 현실적으로 불가능하다.
(출처: 클린코드, CleanCode 정리 - 주석)
이 내용을 보고, 이렇게 생각한다.
"주석은 작성해선 안된다."
나는 주석 == 문서 라고 착각을 했다. 그래서 문서도 등한시 했었다. 코드에 무조건 모두 표현해야한다고 생각했던 것이다. 위 조언들을 다시 잘 생각해보면, 주석 그 자체에 대해서 말하는 게 아니라 코드를 개선하는 것을 말하고 싶은 것 같다. 그 당시, 나는 잘못 이해했었고 자연어로 작성한 무언가는 나의 게으름이라고 판단했었다.
그리고 개발 경험이 좀더 쌓이고 많은 API 문서를 읽으며 개발을 한다. 그리고 내 프로젝트에 새로운 팀원이 들어온다. 주석까지 없애가며(+문서까지 없애가며) 작성했던 나의 코드를 아무리 보여줘도 코드에 대한 질문이 끊이질 않는다. 사실 그냥 내가 코드를 잘 못쓴 걸지도 모름 시간이 좀더 지나 내가 퇴사를 하려고 인수인계를 한다. 인수인계를 할 때도 똑같이 느낀다. 충분히 코드로 표현했다고 생각하지만 질문은 계속된다.
이 시점에, 문서화가 왜 필요한지 느꼈다. 퇴사일를 앞당기려고 그러는거 아님 팀원들이 모두 같은 경험을 하지 않았기에 배경지식이 다르다. 그리고 코드를 작성할 때, 관점이 다르다. 즉, 프로그래밍 세계관이 다르다. 단순히 프로그래밍 세계관 뿐만 아니라, 세상을 해석하는 세계관 자체가 다르다. 그런데, 같은 생각을 하기 바란다는 것은 너무나 큰 착각이였다.
여기까지 읽으면서, 자신에게 비슷한 경험이 있었다면, 이 Docs for Developers: 기술 문서 작성 완벽 가이드 라는 책이 도움이 될 것이다.
