[책 리뷰 / 개발] 개발자의 글쓰기 - 개발자라 쓰고, 작가라 읽는다.

출처 : yes24

 

개발자라고 하는 직업을 떠올리면 코드를 작성하는 모습이 가장 먼저 떠오른다.

 

내가 상상하는 나의 모습 vs 현실

 

사실 개발자도 여타 다른 직업들처럼 보고서를 써야한다. 

장애 보고서, 제안 요청서 등 코드만 치는 것이 아니라 워드나 노션 키고 글을 써야한다.

 

기존에 깨끗한 코드를 작성하기 위한 바이블, 클린코드(나의 리뷰 보러가기)가 있다.

클린코드는 어떻게 변수 이름을 짓고, 함수를 만들고, 주석을 쓰는 지 등 깔끔한 코드 작성을 위한 세세한 내용을 다룬다.

 

이 책도 변수네이밍과 과련된 내용을 다룬다.

하지만 거기서 그치지 않고 고객을 위한 릴리스 노트, 비즈니스 관점에서의 장애 보고서, 기술 블로그 등 개발자가 해야하는 전반적인 글쓰기를 다룬다.

 

개발자는 혼자서 일하지 않는다.

혼자 있는게 좋아도 같이 일해야하는 것이 사회인의 숙명이다.

개발자들과의 협업

개발을 혼자서 하는 경우도 있지만, 보통은 팀 단위로 협업을 한다.

칼같이 역할을 나눠서 한다해도 하나의 프로그램으로 합쳐지는 과정에서 다른 개발자가 작성한 코드와 섞일 수 밖에 없다.

나 뿐만 아니라 다른 개발자들이 읽고 쉽게 이해할 수 있는 코드를 작성해야 한다.

 

책에서 강조하는 것은 가독성과 소통이다.

파스칼 표기법을 쓰든 카멜 표기법을 쓰든 중요한 것이 아니다.

중요한 것은 표기법이 아니라 코드를 읽기 쉽게 작성하는 것이다. 나무위키 표기법 보기

 

최근에는 개발 툴들이 워낙 좋아서 색깔로 쉽게 구별하고 가독성을 높일 수 있다.

하지만 가독성이 높다고 소통이 잘되는 것은 아니다.

소통이 잘 되려면 팀 단위로 같은 컨벤션(Convention)을 지켜야 한다.

 

작년에 동아리 프로젝트로 앱을 만들면서 컨벤션에 대한 중요성을 크게 느꼈다.

PR을 하는 과정에서 함수 이름과 줄바꿈 때문에 코멘트가 달린 것이 한 두번이 아니었다.

초반에는 단순했던 파일 구조도 후반으로 갈수록 복잡해져, 어느 파일이 어느 폴더에 있는지 헷갈렸다.

깔끔한 컨벤션을 정하고 지키는 것이 좋은 프로그램을 만들기 위해 필요하다는 것을 다시금 느낀다.

 

 

비즈니스  용어로도 설명할 수 있어야 한다.

운영하던 쇼핑몰 프로그램 서버에 장애가 발생해서 사용자가 주문을 할 수 없었다고 하자.

다행히 훌륭한 개발자가 있어서 1시간만에 에러를 찾고 복구했다.

프로그램을 훌륭하게 복구했고 이제는 회사 임원에게 보고해야 한다. 

만약 개발자가 서버에서 함수를 호출하는 과정에서 장애가 발생했다는 것을 보고 하면 이렇게 되물을 것이다.

"그래서 회사가 입은 손해가 얼마라는거죠?"

저도 모르는데요?

 

임원들은 비즈니스인 관점으로 본다.

함수 호출 과정에서 발생한 일은 관심도 없을 뿐더러 알고 싶지도 않을 것이다.

개발자는 개발 용어 뿐만 아니라 비즈니스 용어로 설명할 수 있어야 한다.

 

책에서 제시한 방법으로 작성하면 아래와 같다.

항목	내용
장애 내용	사용자 결제 불가 (20xx년 x월 x일 13:00 ~ 14:00)
장애 영향	장애 중 결제시도 50건 결제 실패 평균 결제 비용 3만원 -> 기대 매출 손실 150만원 예상
장애 원인	함수 호출 과정에서 매개 변수 입력 오류로 인한 에러 발생
...	...

데이터를 기반으로 평소에 사용자들이 결제 했던 비용과 장애 중 결제 시도를 합쳐서 기대 매출 손실을 작성하였다.

회사 임원 뿐만 아니라 쇼핑몰을 잘 모르는 사람도 장애로 인해 발생한 손해를 이해할 수 있다.

 

 

 

사용자가 만족해야 한다.

책에 있는 모바일 게임을 예시를 가져왔다.

 

개발자가 버그를 수정하고 새로운 기능을 추가하는 업데이트를 했다.

한 일을 하나씩 적어 체인지 로그를 작성했다.

 

- 고해상도 폰에서 아이콘이 찌그러지는 오류를 수정했습니다.
- 가로/세로 전환 시 하단 메뉴가 사라지는 오류를 수정했습니다.
- 애니메이션 스티커가 갑자기 멈추는 오류를 수정했습니다.
- 미리 보기에서 간혹 리부팅되는 문제를 해결했습니다.
- 용량이 큰 사진을 등록할 때 휴대전화 메모리 사용을 최소화하도록 등록 방식을 개선했습니다.
- 최근 기록이 상위에 올라오도록 개선했습니다.
- 게임 종료 후 바로 순위를 볼 수 있도록 개선했습니다.
- 닉네임을 만들 때 특수 문자를 추가하는 기능을 추가했습니다.
- 빈 게임방을 자동으로 검색하는 기능을 추가했습니다.

열심히 일 한 것은 알겠다.

하지만 글을 열거하기만 해서 가독성이 좋지 않다.

책에서 더 읽기 좋게 수정한다.

 

사용자 편리 개선
	- 게임방에 더 빨리 입장
    - 게임 결과 바로 확인
   
[세부 내용]
* 게임 준비
	- 미리 보기 리부팅 문제 해결
    - 빈 게임방 자동 검색 기능 추가
    - 닉네임 만들 때 특수 문자 입력 기능 추가
* 게임 중
	- 고해상도 폰에서 아이콘이 찌그러지는 오류 수정
    - 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류 수정
    - 애니메이션 스티커가 멈추는 오류 수정
* 게임 종료
	- 최근 기록이 상위에 올라오도록 개선
    - 게임 종료 후 바로 순위를 볼 수 있도록 개선
    - 용량이 큰 사진을 등록할 때 휴대전화 메모리 사용 최소화

 

리스트와 들여쓰기를 사용해 가독성을 높였고, 했습니다와 같은 중복되는 서술어를 제거해주었다.

단순히 열거했을 때보다 훨씬 깔끔하고 분류가 잘 돼있어 원하는 내용만 찾아 볼 수도 있다.

 

 

사용자 풀의 차이가 있을 뿐 모든 프로그램은 사용자가 있다.

개발자, 기획자 뿐만 아니라 사용자도 만족할 수 있도록 글을 적어야 한다. (아따 개발자 할일 많네...)

 

 

 

결국엔 연습이다.

책에서 어떤 식으로 변수 이름을 지으면 좋은 이름이 되는지, 어떤 식으로 작성을 해야 모두가 쉽게 이해할 수 있는지 예시문을 통해 설명해준다.

처음부터 좋은 글을 작성하는 것은 쉽지 않다.

좋은 예시를 보며 많이 써보고 많이 수정해봐야 한다.

 

내 개인적으로 좋은 글은 쉽게 읽히고 쉽게 이해되는 글이라고 생각한다.

책에서는 네이버 공식문서에 대한 칭찬이 많이 나온다.

아직 좋은 글에 대한 기준이 없다면 네이버, 카카오 등 테크 기업들의 공식문서를 참고해보자.

 

 

 

후기

책을 읽기 전에는 클린코드 책을 번역해놓은 정도라고 생각했다.

하지만 클린코드는 코드에 대해서만 다루는데 비해, 개발자가 작성해야하는 글들에 대해 전반적으로 다뤄주었다.

아직 학생으로써 코드를 작성하는 것만으로도 벅찬 나에게 시야를 넓혀주었다.

 

책의 내용도 훌륭하지만 무엇보다도 작가가 한국인이라는 점이 매우 좋다.

기존의 개발 서적의 경우, 번역하는 과정에서 매끄럽지 못한 부분이 많아 이해하기 쉽지 않았다.

이 책의 경우 크게 어색한 부분 없이 매끄럽게 잘 읽혀 좋았다.

 

가끔 책을 읽다 보면 "뭐가 뭐가 문제다" 만 얘기하고 끝내는 책들이 있다. 어쩌라는 건지 싶은 느낌이 든다.

이 책은 단순히 "개발자는 글을 잘 써야 한다"라고 주장하는 것에 그치지 않고, 어떤 식으로 글을 작성하면 좋을지 방향을 제시하고 있는게 이 책의 가장 큰 장점이다.

 

 

학교 도서관에서 빌려서 읽었는데 한 권 사서 두고 두고 읽고 싶다.

개발 공부를 하는 친구들에게 추천해주고 싶다.

아직 안 읽은 사람이 있다면 강추하는 책이다.

😄