개발자의 글쓰기

개발자의 글쓰기

김철수 저

오직 개발자를 위한 글쓰기의 모든 것을 담았다!이 책은 개발자의 글쓰기 능력을 종합적으로 향상하기 위한 책이다. 코드 안에서는 함수와 변수 이름을 짓는 것부터 주석 쓰는 법, 에러 메시지 쓰는 법까지 알려준다. 코드 밖에서는 릴리스 노트, 장애 보고서, 개발 가이드를 어떻게 하면 잘 쓸 수 있는지를 알려준다. 외주...

개발자와 글쓰기의 상관관계

코드는 기본적으로 문자 형태로 표현되는 리터럴이기에 개발자야말로 현존하는 직업 중에서 글쓰기를 가장 많이, 가장 자주 하는 직업이라고 볼 수 있다. 이처럼 많은 글을 쓰는 개발자인데 문제가 몇 가지 있다.

첫째, 코드는 컴퓨터가 읽는 글이며, 사람이 읽는 글과는 구조나 흐름이 다르다는 것이다. 둘째, 개발자가 써야하는 글이 결코 코드뿐만이 아니라는 사실이다. 내부적으로는 개발중인 서비스의 명세부터 장애 보고서, 제안서가 있으며, 외부적으로는 기술블로그, 점검 공지가 있다. 필자와 독자가 모두 개발자인 경우에는 큰 문제가 없을지 모르지만, 개발자의 글을 언제나 개발자만 읽는다는 보장은 결코 할 수 없다.

개발자의 글쓰기

위와 같은 배경으로 저자는 본인의 경험을 담아 개발자의 글쓰기 를 펴냈다. 실제로 저자는 국문과 출신의 개발자로 활동하며, 글쓰기에 어려움을 겪는 주변 동료 개발자를 왕왕 만났다고 밝히고 있으며, 오로지 발군의 개발 실력만 갖춘 사람보다 개발 실력은 평범해도 대외적인 소프트스킬을 지닌 사람을 선호하는 요즘이기에 개발자를 준비하는 학생부터 현업 개발자까지 도움이 될만한 책이라고 생각한다.

이 책에서 저자는 상황, 적에 따라 나뉘는 다양한 케이스의 글쓰기를 다루고 있다. 모든 개발자들이 겪는 최고의 난제 적절한 변수 이름 부터, 릴리스 노트, 장애 보고서 작성 요령과 기술 블로그에 적합한 글쓰기까지 다루는데, 단어 선택 요령과 불필요한 조사 제거 요령, 목적에 따른 글의 구조 등 나 역시도 새롭게 알게 된 부분이 상당히 많다.

개인적으로 인상 깊었던 내용을 짧게 정리해둔다.

목적에 따른 글쓰기 요령

코드

• 다양한 컨벤션이 존재하지만, 우열을 따질 게 아니라 가독성이 우선이며, 동료와 충분히 소통한 뒤 컨벤션을 통일하는 것이 가장 중요하다.
• 이름의 길이가 중요한 것이 아니고, 검색이 잘 되는 이름이 중요하다. 예를 들어 동일한 기능에 사용되는 변수들은 문법에 맞지 않더라도 대표적인 단어가 앞에 오도록 짓는 것이 좋다.

// 추천하지 않는 예시
let speedModeBtn;
let currentSpeedMode;

// 추천하는 예시
let speedModeBtn;
let speedCurrentMode;

• 함수명에는 해당 함수가 수행하는 기능의 목적을 담고, 서술적인 것은 좋지만 없어도 의미가 달라지지 않는 단어는 제거한다. 예를 들어 '사용자의 이름을 input 태그에서 가져오는' 기능을 지닌 함수라면 getUserNameFromField()과 같은 식으로 짓는 것이다.

에러메시지

• 에러메시지는 에러의 원인을 정확하게 전달하는 것이 좋다. 예를 들어 회원가입 페이지에 적용하는 에러메시지일 때, 단순히 '회원가입을 진행할 수 없습니다.'와 같은 내용보다는 보다 구체적으로 '휴대폰 번호는 숫자만 입력해주세요.'와 같이 표현하는 것이 좋다.
• 그 외에도 true, false 값이 적용되는 버튼을 동반한 안내 메시지도 표현에 따라 유저에게 혼란을 가중시킬 수도 있기 때문에 단순하게 '예, 아니오' 보다는 '페이지에서 나가겠습니다. / 페이지에 머물겠습니다.' 처럼 선택에서 비롯되는 정확한 결과를 서술해주는 편이 좋다.

장애 보고서

• 서비스를 운영하다 보면, 예기치 못한 장애가 생길 수 있으며 그에 따른 보고서를 제출하거나 유저를 대상으로 한 공지를 해야 하는 경우가 있다.
• 이럴 때에는 장황하게 서술하기 보다는 범주를 나누어 개조식으로 작성하는 것이 원인과 결과, 조치 등을 한눈에 알아보기 쉽다. 개조식이란 아래의 예시와 같다.

사용자 편리성 개선

• 더 빠른 채널 입장
• 게임 결과 즉시 확인

세부 내용

• 게임 준비

  • 미리보기 리부팅 문제 해결
  • 빈 게임방 자동검색 기능 추가

• 게임 중

  • 고해상도 아이폰에서 그래픽 깨짐 오류 수정
  • 가로/세로 전환 시 메뉴가 사라지던 오류 수정

• 게임 종료

  • 최근 게임 기록이 반영되지 않던 오류 수정
  • 게임 종료 후 바로 순위를 볼 수 있도록 개선

서비스 소개

• 장점과 강점을 헷갈리는 경우가 드물지 않기 때문에 확실하게 구분해야 한다.
• 장점은 절대값이라고 볼 수 있다. 예를 들어 동일 범주에 A, B, C 세 가지 서비스가 있을 때 A와 B 서비스가 잘 하는 부분을 C도 잘 하는 것은 '장점'이라고 볼 수 있다.
• 강점은 상대값으로 볼 수 있다. 예를 들어 위와 동일한 상황에서 A, B에는 없거나 완성도가 떨어지는 부분을 C에서는 빼어난 완성도로 구현하고 있다면 그것은 '강점'으로 볼 수 있다.

기술 블로그

• 주제를 정하고 글을 쓰는 게 어렵다면, '소재'를 중심으로 본인이 진행한 내용에 대해 사실에 기반하여 서술하라.
• 기술 블로그를 찾는 사람들은 일정 수준의 지식을 갖고 있을 확률이 높고, 설사 그 기준에 못 미치더라도 모든 독자의 수준을 고려하는 것은 불가능하다. 독자의 수준에 맞게 쓰지 말고, 자신의 수준에 맞게 작성하라.
• 기술 블로그라고 해서 꼭 딱딱하고, 언제나 객관적일 필요는 없다. 재미있게 작성하라.

다른 북리뷰:

• 프로그래밍 심리학
• 프로그래머의 길, 멘토에게 묻다
• 조엘 온 소프트웨어
• 클린코드, 클린코더