[23년 2분기] 개발자의 글쓰기

책 제목부터 나에겐 매우 흥미로웠다.
미디어보다 글을 훨씬 더 좋아해서 글쓰기와 읽기에 관심이 많다.
그냥 읽으면 나중에 기억이 잘 안 날 것 같으니 간단하게 메모.

---

네이밍 컨벤션, 이유를 알고 쓰자

이름 짓기는 창조가 아니라 조합

자바 네이밍 컨벤션

• 클래스는 UpperCamelCase
• 함수와 변수는 lowerCamelCase
• 상수는 UPPER_DELIMITOR_CASE

함수는 동작을 시키는 명령어 개념이므로 첫 단어가 주로 동사
변수는 형용사로 시작하는 경우도 많다.
영어 표기 원칙으로 명사가 아닌 경우 첫 글자를 소문자로 시작하기 때문에 함수와 변수는 모두 첫 단어의 첫 글자를 소문자로 쓴다.

변수 이름을 잘 짓는 법

중요한 단어를 앞에 쓴다

int totalVisitor	int visitorTotal
int totalRegister	int RegisterTotal
int maxSizeOfWindow	int windowSizeMax

왼쪽이 아닌 오른쪽으로 쓴다.
그렇지만 개인적으로 max를 뒤로 쓰는 게 꽤 어색하다.

Count 같은 것도 계속 앞에 쓰고 싶음..

 

 

함수 이름 짓는 순서

1. 필요한 기능들을 나열한다.
2. 논리적으로 합쳐야 하거나 떼야할 것을 정리한다.
3. 함수 문장들을 영어로 바꾼다.
4. 불필요한 단어들을 빼고 네이밍컨벤션에 따라 바꾼다.

 

 

비즈니스를 이해하는 장애 보고서 쓰기

장애보고서 항목

1. 뭐야 무슨 일이야? : 장애 내용

2. 그래서 어떻게 됐어? : 장애 영향

3. 왜 그렇게 됐어? : 장애 원인

4. 넌 어떻게 했는데? : 조치 사항

5. 이제 장애는 해결된 거야? : 조치 결과

6. 누가 잘못한 거야? : 핵심 원인

7. 이제 어떻게 할거야? : 향후 대책

 

5Whys로 재발 막기

원인 대신 이유를 물어야 한다.

 

1. 로그인 기능이 작동하지 않은 이유가 무엇인가?

->사용자가 아이디를 13글자 이상 입력했다.

2. 사용자가 13글자 이상을 입력하는 이유가 무엇인가?

->프런트 개발자가 13글자 이상 입력하게 허용했다.

3. 프런트 개발자가 13글자 이상 입력하게 허용한 이유가 무엇인가?

->서버 개발자가 아이디 글자 수를 16글자에서 12글자로 제한한 사실을 프런트 개발자가 몰랐다.

4. 프런트 개발자가 그 사실을 모른 이유가 무엇인가?

->서버 개발자가 프런트 개발자에게 알리지 않았다.

5. 서버 개발자가 그 사실을 프런트 개발자에게 알리지 않은 이유가 무엇인가?

->서버 개발자는 데이터베이스 개발자가 알려줄 것이라 생각했다.

 

서비스 개념을 범주, 용도, 특징 순으로 설명하자

독자가 잘 아는 범주를 먼저 말하고

그 범주의 용도를 말하면 서비스의 용도와 같음을 알아차린다.

마지막으로 차별화하는 특징을 말하면 독자는 서비스의 개념을 정확히 이해한다.

예)

(범주)Amazon Simple Storage Service(Amazon S3)는 인터넷 스토리지 서비스입니다.

(용도)Amazon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다.

(특징)AWS Management Console의 간단하고 직관적인 웹 인터페이스를 통해 이러한 작업을 수행할 수 있습니다.

 

장점과 강점

장점 : 자기가 할 수 있는 여러 가지 중에 잘하는 것.

강점 : 다른 경쟁사보다 잘하는 것.

 

 

글의 종류별로 목차 잡는 법

기술 블로그의 4종류

저 : 직접 경험하고 실험한 과정이나 결과 / 개발기, 도입기, 적용기

술 : 어떤 것을 분석하여 의미를 풀이하고 해석한 것 / 기술 소개, 용어 분석, 에러 해결 방법

편 : 산만하고 복잡한 자료를 편집해 질서를 부여한 것 / 프로그램 설치, 설정 방법, 튜토리얼, 세미나 후기, 책 리뷰

집 : 여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것 / 명령어 모음, 팁, ㅇㅇ가지 규칙

 

저 : 개발기는 목차를 잘 잡아서 본문부터 쓰자

직접 경험한 것.

목차를 잘 구성하면 다른 종류의 글보다 쓰기 쉽다.

머리말/본문/맺음말 이라고 하면,

가장 쓰기 어려운 것이 머리말이기 때문에 본문부터 쓰고, 맺음말, 머리말 순으로 쓴다.

 

술 : 원전을 비교하고 실험해 풀이해서 쓰자

어떤 것을 분석해 의미를 풀이하고 해석한 것.

 

편 : 순서를 요약하여 쓰자

산만하고 복잡한 자료를 편집해 질서를 부여한 것.

할 일을 순서대로 얘기하는 것이 아니라 적정한 단계로 나눠서 설명한다.

(1.2.3.4 순서가 아닌 1단계 1.2.3 , 2단계 1.2.3 이런 식)

 

집 : 글쓰기가 두렵다면 자료를 모아 핵심을 엮어서 쓰자

여러 사람의 견해나 흩어진 자료를 한데 모아 정리하는 것.

 

 

 

---

읽고 나서.

책에 초반부에 개발자가 쓰는 글들은 메모장에 쓰는 것 같다..라고 하는 비개발자의 말이 정말 와닿았다.

처음엔 이게 무슨 말인지 정확하게 이해하지 못했는데,

중요도를 나타내기 위한 문단모양(제목/본문), 글자 크기와 색, 강조 같은 게 없이 그냥 '글'만 있는 글을 보고 그렇게 표현한 문장이었다.

 

생각해 보니 나도 업무 메신저나 문서에서 주어진 양식 이외에는 특별히 고려하지 않은 상황이 많았다.

당연한 얘기일 수도 있으나 왜 그렇게 써야 하는지, 또는 예문과 나쁜/좋은 예들이 들어있어서 어렵지 않게 이해할 수 있었다.

글쓰기 책이다 보니 잘 써진 책이라서 그럴까..? 중간중간 환기가 되는 느낌도 있어서 지루하지 않았던 것 같다.

 

팀비로 구입해서 읽은 책인데 다른 팀원들에게나 지인들에게 한 번쯤 편하게 읽어보라고 추천해주고 싶다.