[독서정산] 개발자의 글쓰기

개발자의 글쓰기

이제 막 개발을 시작하는 주니어 단계의 개발자들에게는 많은 도움이 될 것 같은 책이라고 생각한다. 또한 해당 내용을 잘 아는 개발자들도 복습하듯 가볍게 읽을만하다. 당연한 이야기들이지만 중요하고 필요한 이야기들이 많았다. 결국 글쓰기 라는 것도 그 글을 읽을 누군가에게 메시지를 전달하기 위함인 것이고 독자를 생각해서 글을 작성해야 한다. 글을 잘 쓰는 것은 너무 어려운 과정이고 의도적으로 훈련을 해야 한다고 생각한다.

제목

개발자의 글쓰기 - 변수 네이밍부터 릴리스 노트, 장애 보고서, 기술 블로그까지, 프로그래머의 글스기 고민 끝!

저자

김철수 저

출판사

위키북스

발행일

2019년 10월

인상 깊은 문장

• (p20) 기획자나 관리자의 글쓰기에 논리력, 설득력, 실행력이 중요하다면, 개발자의 글쓰기에는 정확성 (틀림이 없이 확실한 것), 간결성 (간단하고 깔끔한 것), 가독성(쉽게 읽히는 것)이 중요하다.
• (p29) 글을 표현하는데는 크게 3가지 방법이 있음. 서술식 (~다 로 끝나는 완전한 문장): 줄거리가 있는 설명이나 이야기를 작성할 때, 개조식 (~ 했음 처럼 명사형으로 끝나는 문장): 여러 가지 종류의 항목과 내용에서 강조가 필요한 경우, 도식 (테이블, 도표 등): 각 항목이나 사항의 관계를 명확히 규정하고 싶을 때
• (p43) 정확한 단어를 사용하는 것도 중요하지만 그보다 더 중요한 것은 얼마나 일관성있고 개연성 있게 쓰느냐다. 프로그램 안에서 일관성과 개연성이 있다면, 또는 그 프로그램의 코드를 보는 개발자 사이에 일관적이고 개연적인 합의만 돼 있다면 어떻게 쓰든 상관없다.

비슷한 단어들을 잘 사용하기 위해서 팀에서 회의를 통해 find, get, search 에 대해 정리한 적이 있다. 참고

• (p55) 코드 컨벤션을 만든 이유는 가독성과 소통 때문이다. 남들이 으리 그렇게 하니 따라 할 것이 아니라 그렇게 쓰는 이유를 알고 써야 한다.
• (p76) 이름을 잘 지으면 주석을 줄일 수 있다.
• (p97) 사용자가 404 에러 페이지를 만나는 것을 죄송하게 생각한다면 당연히 사용자가 404 에러 페이지를 만나지 않게 만들어야 한다.
• (p99) 개발자용 에러 메시지와 사용자용 에러 메시지를 분리하자

어드민 페이지를 만들다보면 백엔드에서 제공하는 개발자용 에러 메시지가 그대로 어드민 화면에 노출되는 경우가 종종 있는데, 이에 대해 깊게 이야기해보면 좋았을 것 같다는 생각이 든다. 추후 비슷한 작업을 하게 된다면 백엔드에서 제공할 에러 코드를 정리하고 해당 에러 코드에 따라 프론트에서 노출할 에러 메시지를 명확히 정리해보면 좋겠다.

• (p103) 에러 메시지는 내용, 원인, 해결 방법이 포함되면 좋다.
• (p147) 장애 보고서는 개발자가 원할 때 쓸 수 없다. 장애의 1차 원인은 대부분 다른 원인의 결과다. 장애 보고를 받는 윗사람은 대부분 개발자가 아니다. 장애를 해결했다고 해서 100% 해결한 것은 아니다. 

경험상 장애보고서에서 가장 중요한 것은 Business Impact 의 유무와 그 정도였던 것 같다. 몇 시간동안 어떤 기능이 동작하지 않아 얼마 만큼의 손실이 발생했는지 등... 이 데이터를 찾아내기 위해서 보통 로그를 확인하거나 하루 전, 일주일 전 데이터와 얼마나 차이가 나는지 등을 정리해야 하는데 평소에 로그를 잘 안남겨놓거나 데이터를 만들어두지 않으면 이 과정이 매우 힘들다.

• (p174) 정확히 이해하도록 그림과 글로 묘사하자

글로만 전달하는 것과 그 글에 대한 Visual aid 가 최소 하나라도 있는 것은 전달력에 있어서 엄청난 차이가 있다고 생각한다. 글을 읽고 서로 다른 이해를 할 여지를 최소화할 수 있기 때문이다. 다만 이게 하기 힘든 이유가 귀찮고, 일단 나부터 이해가 명확히 되어야 그림으로 시각화 할 수 있기 때문이다.