개발자의 글쓰기 (2019/김철수/위키북스)

 

통근하면서 왕복 4시간이 아까워 작은 슬링백에 들어갈 정도 크기의 개발 서적들을 읽기로 했다.

개발 서적들은 두꺼운 게 많기 때문에

작은 책들은 주로 코드가 들어가 있는 책보다는 개발 방법론을 다룬 책들이 많다. 

 

리뷰는 남에게 보여주는 용도보다는 요약해서 나중에 글 내용을 회고하기 위한 목적으로 작성.

 

첫 번째로 읽어본 책은 개발자의 글쓰기.

요즘 릴리즈 노트를 쓰는 일이 잦고, 일단은 이 블로그는 기술 블로그에 가깝긴 해서 부제만 보고 결정.

부제는 '변수 네이밍부터 릴리스 노트, 장애 보고서, 기술 블로그까지, 프로그래머의 글쓰기 고민 끝!'이다.

 

 

중요한 부분 요약

1. 변수 네이밍에는 원칙이 있다.

 - 파스칼(PascalCase) 표기법으로 클래스 이름 짓기

 - 카멜(camelCase) 표기법으로 함수·변수의 이름 짓기

 - 네이밍은 3 단어에 16글자 이내를 원칙으로 하자. 

 - 네이밍은 동사 + 명사 + 명사로 짓자.

 

2. 좋은 코드는 주석이 없다.

 - 네이밍을 간단하게 짓고 그 의미를 설명하는 주석을 다는 것은 안 좋은 습관이다.

 - 네이밍에서 해당 변수/클래스/함수의 의미를 알 수 있도록 하자.

 

3. 릴리즈 노트를 쓸 때 독자 관점에 쓰자.

 - 내가 특정 기능을 고치는데 힘들었다고 해도 사용자는 관심 없다.

 - 사용자가 관심 있는 수정점을 1순위로 적고, 개발자가 관심있는 수정점을 2순위로 적자.

 

4. 가이드 작성에는 번호를 표기하자.

 - 스크린샷에 번호를 넣은 설명을 적을 때,

   번호별로 문장을 적는 것보다 한 문장으로 요약하고 번호를 같이 표기하자. 

 

(나쁜 예)

 1. 사이드바 메뉴에서 설정을 클릭하여 확장 메뉴를 펼칩니다.

 2. 푸시를 선택하여 푸시 설정 화면으로 이동합니다.

 3. 푸시 섹션에서 푸시 사용 버튼을 On으로 켭니다.

 

(좋은 예)

 1. 푸시 알림을 설정하려면 ①확장 메뉴에서 ②푸시 화면에서 ③푸시 사용을 켭니다.

 

5. 가이드 작성이 길어지면 단계를 나누자.

 - 나열식으로 하다 보면 독자는 전체 지시를 따르지 않고 중간에 포기해버린다.

 - 특정 단계를 묶어서 소제목을 붙이면 가독성이 오른다.

 

(나쁜 예)

 1. OpenDemo를 클릭합니다. 데모가 새 탭에서 열립니다.

 2. 데모에서 Number 1에 1을 입력합니다.

 3. Number 2에 1을 입력합니다.

 4. 데모에서 Command+Option+I(Mac) 또는 Control+SHift+I(Windows, Linux)를 눌러서 DevTool을 엽니다.

   ...

 

(좋은 예)

1단계 : 버그 재현

 1. OpenDemo를 클릭합니다. 데모가 새 탭에서 열립니다.

   ...

 

2단계 : 실행 코드 검색 및 일시 중지

 1. 데모에서 Command+Option+I(Mac) 또는 Control+SHift+I(Windows, Linux)를 눌러서 DevTool을 엽니다.

   ... 

6. 고객은 자기가 원하는 제품이 정확히 뭔지 모른다.

 - 고객의 요구사항을 그대로 받아서 분석해서 개발하지 말고,

   고객에게 요구사항을 제시해서 고객이 선택하게 만들어야 한다.

 - 요구사항의 문제점을 제시하고, 대안을 제시하자.

 

 

 

 

개발서 치고는 전체적으로 가볍게 읽기 좋은 책이다.

중간 중간 멈춰서 깊게 생각해야 될 부분도 없어서 1~2시간 정도면 다 읽을 수 있다.

 

가장 와 닿았던 부분은 '내가 특정 기능을 고치는데 힘들었다고 해도 사용자는 관심 없다.'라는 문장.

릴리즈 노트를 쓸 때 내가 그 기능을 구현하는데 힘들었다고 해서 고객이 그것을 알아야 할 의무는 없다.