[독서록] 개발자의 글쓰기

개발자의 글쓰기

책을 선택한 계기

업무에서 작성하는 문서와 코드의 가독성이 점점 중요해지는 것을 체감하면서, 글쓰기를 체계적으로 배울 필요가 있다고 느꼈다. 그러던 중 이 책을 접하게 되었고, 개발자가 왜 글을 잘 써야 하는지, 또 어떻게 글을 잘 쓸 수 있는지 배우고 싶어 이 책을 읽게 되었다.

 

책의 핵심 내용

'개발자의 글쓰기'에서 저자는 개발자의 글쓰기를 특징짓는 세 가지 원칙으로 정확성, 간결성, 가독성을 꼽는다. 흥미로운 점은 이 세 가지가 서로 긴장 관계에 있다는 점이다. 정확성을 높이면 문장이 길어져 간결성과 가독성이 떨어지고, 간결성을 강조하면 정확성이 희생될 수 있다. 그러나 꾸준한 공부와 연습을 통해 세 가지 요소를 균형 있게 담아내는 글쓰기가 가능하다고 강조한다.

또한 글을 쓸 때 중요한 것은 문장과 단락의 구조화이다. 문장을 표현하는 방식은 크게 서술식, 개조식, 도식으로 나눌 수 있다. 서술식은 설명이나 논증에, 개조식은 릴리스 노트나 장애 보고서처럼 항목을 나열할 때, 도식은 표나 그림으로 구조를 나타낼 때 적합하다. 문서의 목적에 맞는 구조를 선택하는 것이 곧 효과적인 글쓰기다.

 개발자의 글쓰기에서 특히 두드러지는 부분은 네이밍(naming)이다. 변수, 함수, 클래스 이름을 짓는 과정은 단순한 창조가 아니라 원칙에 따른 단어 선택과 조합이다. 저자는 좋은 이름이 갖추어야 할 다섯 가지 특성을 SMART(Search, Mix, Agree, Remember, Type)로 정리하며, 가독성과 소통을 위해 네이밍 규칙과 팀 컨벤션을 지키는 것이 중요하다고 강조한다.

 이와 더불어, 문서에서 주석의 반복이 필요한 경우도 있다는 점을 짚는다. 예컨대 특정 코드에 대한 설명이 중복되더라도, 개발 문서를 부분적으로 찾아보는 사용자를 위해 동일한 주석을 반복하는 것이 오히려 친절한 글쓰기다.

 마지막으로, 에러 메시지와 알림 문구도 글쓰기의 일부임을 강조한다. 이는 단순한 시스템 피드백이 아니라 사용자와의 소통 수단이기 때문에, 개발자의 시각이 아니라 사용자의 입장에서 이해하기 쉽게 작성해야 한다.

느낀점

이 책을 읽으면서, 그동안 내가 얼마나 글쓰기를 단순 기록으로만 생각했는지 반성하게 되었다. 특히 변수명이나 함수명을 지을 때 짧고 편의적인 표현을 선호했지만, 그것이 협업 과정에서 오히려 혼란을 초래할 수 있다는 사실에 공감했다. 주석 역시 불필요한 반복이라 여겼는데, 사용자의 맥락을 고려하면 반복이야말로 이해를 돕는 글쓰기라는 점이 인상 깊었다.

또한 에러 메시지를 사용자와의 소통으로 본다는 관점은 새로웠다. 지금까지는 개발자의 입장에서만 문구를 작성했기에, 사용자에게 직관적이지 않았다는 사실을 떠올리며 스스로 부족함을 느꼈다. 이 책을 통해 개발자의 글쓰기가 결국 협업과 배려의 기술임을 깨달을 수 있었다.

 

앞으로의 다짐

앞으로는 글쓰기를 단순한 부수 작업이 아니라 개발 역량의 핵심 요소로 인식하고 실천할 것이다.

• 네이밍에서는 SMART 원칙을 적용해 의미가 분명하고 협업자가 쉽게 이해할 수 있는 이름을 짓는다.
• 문서 작성 시 목적에 맞는 구조(서술식·개조식·도식)를 선택해 글의 가독성을 높인다.
• 주석은 동료의 이해를 돕는 도구임을 기억하며 작성한다.
• 에러 메시지나 안내 문구는 사용자 중심으로 작성하여, 시스템과 사용자 간의 소통을 원할하게 만든다.

결론

'개발자의 글쓰기'는 단순한 글쓰기 지침서가 아니라, 개발자의 업무 전반에 걸친 소통과 협업의 철학을 담은 책이었다. 이 책을 읽고 얻은 통찰을 실제 업무와 글쓰기 습관에 녹여냄으로써, 더 나은 개발자이자 협업자가 되고자 한다.