[책리뷰] 개발자의 글쓰기, 김철수 지음

각 챕터별 상황에 따라 읽으면 좋을 시기

[프롤로그] ~[2장]_신입 개발자가 기초를 탄탄히 할 때

[3장] ~ [4장]_실제 소프트웨어를 서비스하고 있을 때

[5장]_개발 가이드 작성이 어려울 때 

[6장]_SI 제안서 작성할 때

[7장]_포트폴리오 준비 등으로 기술 블로그를 작성하려는 데 어려움을 겪을 때

---

[프롤로그] 개발자의 글쓰기는 달라야 한다.

개발자는 글을 못 쓴다?

개발자의 글쓰기의 특징: 정확성, 간결성, 가독성

개발자의 글쓰기

 

[1장] 개발자가 알아야 할 글쓰기 기본

01_문장과 단락을 구조화하는 법

문장을 구조화하는 법

서술식, 재조식, 도식의 차이

개조식 서술 방식과 글머리 기호

단락을 구조화하는 위계

02_쉽게 쓰는 띄어쓰기와 문장 부호

가장 쉬운 띄어쓰기 원칙

"조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어 쓴다."

오해하기 쉬운 문장부호(큰따옴표, 작은따옴표)

큰따옴표: 글에서 직접 대화를 표시하거나 말이나 글을 인용할 때 사용
작은따옴표: 인용한 말 안에 있는 인용한 말, 또는 마음속으로 한 말을 쓸 때 사용

03_영어 단어 선택과 외래어 표기법

비슷한 듯 다른 듯, 단어 선택

외산 제품 표기와 외래어 표기법

국립국어원 외래어 표기 용례 찾기: https://kornorms.korean.go.kr/m/m_exampleList.do

한국어 어문 규범

영어가 아닌 언어를 우리말로 변환시

한글라이즈: https://hangulize.org/?lang=aze&word=jurnal 

[2장] 개발 시간을 줄여주는 이름 짓기와 주석 쓰기

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

개발자의 가장 큰 고민은 이름 짓기

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

깃허브의 인기 자바소를 분석해서 클래스, 함수, 변수 이름의 명명 특징을 연구한 블로그

"오픈소스의 네이밍 특징들"

• 자바 네이밍 컨벤션을 철저히 준수한다.
  • 클래스는 UpperCamelCase : 첫 글자 대문자
  • 함수와 변수는 lowerCamelCase : 첫 글자 소문자
  • 상수는 UPPER_DELIMITER_CASE : 모두 대문자
• 네이밍은 보통 16글자, 3단어를 조합한다.
  • 클래스 네임: 3.18단어
  • 함수 네임: 3.36단어
  • 변수 네임: 2.57단어
• 품사는 주로 명사, 동사, 형용사의 조합이다.
  • 명사 + 명사 + 명사
  • 동사 + 명사 + 명사
  • 형용사 + 명사 + 명사 등

코드의 네이밍 컨벤션은 영어 표기법을 상속받았다

| 파스칼 표기법으로 클래스 이름 짓기 > 모든 단어에서 첫 글자를 대문자로 쓰는 방식

interface Menu
class CoffeMenu implements Menu

| 카멜 표기법으로 함수·변수의 이름 짓기 > 첫 단어만 빼고 나머지 단어의 첫 번째 글자를 대문자로 쓰는 방식

int totalCount = 0;
void orderCoffee()

| 상수는 모두 대문자로 쓴다

static final int COFFEE_MAX = 10;

| 패키지와 모듈은 모두 소문자로 쓴다

kr.co.wikibook.android.developerwriting
import developerwriting

| BEM 표기법: Block, Element, Modifier > 대상-요소__상태

대상의 요소나 부분을 의미할 때는 언더스코어 두 개(__)

대상이나 요소의 상태나 속성을 의미할 대는 하이픈 두 개(--)

.form {}
.form__button {}
.form__button--disabled {}

가독성과 소통이 먼저다

---

02_변수 이름을 잘 짓는 법

i는 변수 이름이지만 d는 아니다

[좋은 예]
int someday
int today
int thisMonth
int finalYear
--------------------------
int daysSinceCreated
int monthsSinceUpdated
int yearsSinceRegistered

| 긴 이름? 짧은 이름? 검색 잘 되는 이름!

button > btn,  image > img로 작성하는 방식의 헝가리안 표기법은 옛날에는 좋은 수단이었지만, 변수의 자동완성이 지원되면서 그 편의성은 점차 떨어지고 있다.

| 복수형을 나타내는 s를 붙일까 말까?

> s는 눈에 잘 띄지 않으므로, 생략해도 무관. 단!! 통일성을 지킬 것

| 약어를 쓰는 것이 좋을까? 안 쓰는 것이 좋을까?

> 약어로 많이 사용하는 용어라면 사용 ok.

| 중요한 단어를 앞에 쓴다

int visitorTotal
int registerTotal
int buyerTotal
int salesOfThisMonthTotal
int windowSizeMax
int vipCount

| 함수 이름 짓는 순서

예를 들어, 회원가입을 하는 웹페이지에서 다음과 같은 기능이 있어야 한다고 하자.

"사용자가 이름을 입력하고 등록 버튼을 클릭하면, 시스템이 사용자 이름을 input 태그에서 가져와 이름 입력 여부와 글자 수를 확인한 후 입력이 안 되었으면 스크립트를 중단하고 input 태그를 활성화해 사용자가 쓸 수 있게 하고, 글자 수가 한글 두 글자 이하면 확인을 요청해 사용자가 확인할 수 있게 한다."

이를 함수 이름으로 그대로 옮길 수는 없다. 그래서 일단 사용자가 할 일을 모두 없애서 문장을 간결하게 만드렁야 한다. 함수는 시스템이 할 일을 나타내는 것이지 사용자가 할 일을 나타내는 것이 아니다. 따라서 함수의 주체, 즉 주어도 없앤다.

논리적으로 합쳐야 하거나 떼야 할 것을 확인해서 다시 정리한다. 두 번째 줄의 "이름을 input 태그에서 가져와 입력 여부와 글자 수를 확인"에서 입력 여부는 글자 수로 알 수 있다. 글자 수가 0(=null)이면 입력이 안 된 것이다. 따라서 "입력 여부"를 확인하는 것은 "글자 수 확인"으로 대신할 수 있다.

세번째 줄의 "스크립트를 중단"하는 것도 지우자. 이름이 한 글자도 없으면 당연히 스크립트 실행을 중단해야 한다.

"사용자가 이름을 입력하고 등록 버튼을 클릭하면 시스템이 사용자 이름을 input 태그에서 가져와 입력 여부와 글자 수를 확인한 뒤 입력이 안 되었으면 스크립트를 중단하고 input 태그를 활성화해 사용자가 쓸 수 있게 하고, 글자 수가 한글 두 글자이하면 확인을 요청해 사용자가 확인할 수 있게 한다.

이제 남은 문장을 조각내자.

1. 사용자 이름을 input 태그에서 가져온다.

2. 사용자 이름의 글자 수를 확인한다.

3. 입력이 안 되었으면 input 태그를 활성화한다.

4. 글자 수가 한글 두 글자 이하면 확인을 요청한다.

이제 함수를 몇 개 쓸지 결정한다. 일은 1 함수 1업무 규칙을 적용하자. 예문에서 3, 4번은 2번에 속하는 동작이므로 2~4번을 함수 하나로 묶을 수 있다. 이때 문장을 논리로 다시 구성하자.

1. (함수1) 사용자 이름을 input 태그에서 가져온다.

2. (함수2) 사용자 이름의 글자 수가 2글자 이하면 다음과 같이 처리한다.

 > 만약 글자 수가 0(=null)이면 input 태그를 활성화한다.

 > 만약 글자 수가 1 또는 2이면 사용자에게 확인을 요청한다.

이제 함수 문장을 영어로 바꾸자.

• (함수1) 사용자 이름을 input 태그에서 가져온다.
→ get user's name from the text input field

• (함수2) 사용자 이름의 글자 수가 2글자 이하면 다음과 같이 처리한다.
→ do something if user's name contains under 2 characters

영문에서 정관사나 불필요한 단어를 빼고 of는 앞뒤 단어를 바꾸자. 소유격도 없애자. do something은 확인해 처리하는 check로 바꾸자.

• (함수1) get user name from input field
• (함수2) check if user name contains under 2 characters

이제 띄어쓰기를 없애고, 두 번째 단어부터는 첫 철자를 대문자로 바꾸자.

• (함수1) getUsernameFromInputField()
• (함수2) checkIfUserNameContainsUnder2characters()

함수를 사용할 때 의미상 없어도 되는 단어는 없애자.

• (함수1) getUsernameFromField()
• (함수2) checkUserNameUnder2Characters()

03_좋은 이름의 기준, SMART

한 번에 좋은 이름을 지을 수는 없다

좋은 이름이 가진 5가지 특징

easy to Search: 검색하기 쉽게 이름 짓는 법

[접두어로 카테고리화 하기]
ERROR_SERVER_TIMEOUT
ERROR_NO_RESULT
ERROR_BAD_REQUEST
ERROR_SERVER_ALLOWED_REQUESTS_EXCESS
-------------------------------------------------------
user
userBuyer
userPayer
userRegister
userRegisterButNoPayer

easy to Mix: 조합하기 쉽게 이름 짓는 법

[기존 태그와 조합해 이름 짓기]
h1. title
h2. title
p.title
img.title

easy to Agree: 수긍하기 쉽게 이름 짓는 법 > 구별할 필요가 없다면 이름지을 필요는 없다

easy to Remember: 기억하기 쉽게 이름 짓는 법 > 시청각적 이름을 짓자.

ex. SSG(쓱), SBS뉴스(스브스뉴스) ...

easy to Type: 입력하기 쉽게 이름 짓는 법

> 자주 사용되거나 중요한 이름이라면 입력하기 쉬운지, 오타를 낼 가능성이 작은지, 다른 사람에게 말로 전달하기 쉬운지 검토해 보는 것이 좋다.

Ref.

• 연속된 철자: successes, classes, committee, parallel
• 묵음: lambada, thumbnail, debt
• ie/ei: chief, receive, retrieve, friends, achieve
• sion/tion: position, commission
• uous/ous/us: continuous, fabulous, genius

04_좋은 코드에는 주석이 없다?

이름을 잘 지으면 주석을 줄일 수 있다

[안 좋은 예]
// 스크린 최대 높이를 480으로 지정함
int h = 480
[좋은 예]
int screenHeightMax = 480

처음부터 주석 없이 코딩하는 연습을 하자

| 주석이 필요한 때도 많다

> 의미에 따라 쓰이는 영어단어가 다르다. 따라서, 이 경우에는 주석으로 추가 설명을 해주는 것이 좋다.

checkUserNameUnder3Characters() // 3글자 이하인지 체크

05_다른 개발자를 배려하는 주석 쓰기

코드는 의미를, 주석은 의도를

letsEatSomething() // 내가 배가 고픈 상황
letsEatSomething() // 네가 배가 고픈 상황
letsEatSomething() // 내가 심심한 상황

ex. 이유를 알려주는 것, 개발자가 새롭게 발견한 것, 예상 질문과 답, 할 일이나 주의, 개선 아이디어를 주는 것, 다른 사람에게 보완을 요청하는 것, 개발자의 속마음을 표현한 것

[할 일이나 주의, 개선 아이디어를 주는 것]
// TODO: 동영상이 아닌 동영상 확장자를 확인하는 기능을 넣을 것
// XXX: null이 입력되면 무한 루프가 발생할 가능성이 있음
// HACK: 이 스크립트는 받는 페이지에서 처리하는 것이 낫다.
// 이 버튼은 한 번만 호출하면 됩니다.

| 주석의 반복

> 전체를 보는 코드라면 반복되는 주석은 없애는 것이 좋다. But, 중간중간 참고용으로 찾게되는 코드 or 개발 가이드 문서는 같은 주석이라도 반복해서 써주는 것이 좋다.

주석의 발췌와 요약

| 주석도 코드다

> 코드는 디버깅할 수 있지만, 아직 주석은 잘못된 곳을 수동으로 찾아야 한다.

---

[3장] 사용자와 소통하는 에러 메시지 쓰기

01_에러 메시지를 쓰기 전에 에러부터 없애자

친절한 404, 불친절한 404

404 에러가 죄송할 일인가?

| 깨진 링크는 개발자의 책임이다

깨진 링크 찾는 사이트: 브로큰링크체크닷컴, 구글 서치콘솔

개발자용 에러 메시지와 사용자용 에러 메시지를 분리하자

02_사용자 에러 메시지를 제대로 쓰는 법

사용자 에러에 대처하는 메시지

에러 메시지를 보여주는 순서

오락가락 메시지와 버튼 메시지

03_사용자의 에러를 줄이는 메시지 구조화

버튼의 순서

사용자의 반복 에러를 막는 법

04_에러 메시지 대신 예방 메시지를 쓰자

서비스를 이해하면 에러를 예방할 수 있다.

사용자를 이해하면 에러를 예방할 수 있다.

닭이 먼저? 알이 먼저?

 

[4장] 독자 관점에서 릴리스 문서와 장애 보고서 쓰기

01_체인지 로그를 분류, 요약, 종합하는 법

체인지 로그의 양과 만족도의 관계

1단계: 선정하기

2단계: 분류하기

3단계: 요약하기

4단계: 종합하기

02_고객에게 유용한 정보를 쓰자

개발자 관점과 고객 관점

과거를 리뷰하고 미래를 보여주자

Semantic Vesioning(유의적 버전)

03_릴리스 문서는 문제 해결 보고서처럼 쓰자

문제와 문제점을 구별하자

문제, 문제점, 해결책, 후속 계획 순으로 적자

법적인 문제를 고려해서 쓰자

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

장애 보고서의 특징

질문에 대답하는 신속한 글쓰기

원인과 이유를 찾는 분석적 글쓰기

상사를 고려하는 비즈니스 관점의 글쓰기

원하는 것을 얻는 정치적 글쓰기

---

[5장] 설명, 묘사, 논증, 서사로 개발 가이드 쓰기

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

범주, 용도, 특징

범주를 정확하고 적절하게 선택하자

용도를 범주의 핵심 기능으로 기술하자

특징을 장점과 강점에서 뽑아 쓰자

02_정확히 이해하도록 그림과 글로 묘사하자

글에 묘사를 더하면 이해가 빠르다

글과 그림의 내용을 일치시키자

객관적 묘사와 주관적 묘사 둘 다 하자

03_논증으로 유용한 정보를 제공하자

의견을 쓰려면 근거를 대자

거칠게도 공손하게도 쓰지 말자

주장과 이유의 거리를 좁혀서 쓰자

문제와 답의 거리를 좁혀서 쓰자

04_서사를 활용해 목차를 만들자

개발과 서사

독자의 수준 대신 기술의 범용성을 기준으로 쓰자

순서에서 단계를, 단계에서 목차를 만들자

---

[6장] 수주를 돕는 SI 제안서 쓰기

01_개발자가 알아야 할 제안서 작성 원칙

개발자와 제안 PM의 차이

시스템 구성도의 본질은 그림이 아니다

첫째, 제안요청서 분석

둘째, 논리적 완결성

02_고객의 문제 인식과 제안사의 문제 해결 능력

문제 인식과 문제 해결 능력

① 경쟁사와 비교하여 제안하라

② 일단 동감하고 다른 방안을 제시하라

③ 고객이 문제를 중대하게 인식하게 만들어라

④ 경쟁사의 전략을 확인해서 대처하라

03_고객의 요구사항은 변할 수밖에 없다

개발은 고객 요구 실현

요구사항을 분석하지 말고 제시하라

변화하는 요구사항에 대비하라

04_고객의 총 만족도를 높이자

요구라고 다 같은 요구가 아니다

카노 모델로 본 요구의 세 가지 종류

---

[7장] 기술 블로그 쉽게 쓰고 운영하기

01_기술 블로그를 쉽게 쓰는 방법 3가지

개발자가 기술 블로그를 잘 못 쓰는 이유

첫째, 주제 의식을 버리고 소재 의식으로 쓰자

둘째, 독자 수준이 아니라 자기 수준으로 쓰자

셋째, 재미있게 글을 쓰자

02_글의 종류별 목차 잡는 법 I - 저술

기술 블로그의 4종류, 저, 술, 편, 집

구분	내용	종류
저	직접 경험하고 실험한 과정이나 결과	개발기, 도입기, 적용기
술	어떤 것을 분석하여 의미를 풀이하고 해석한 것	기술 소개, 용어 분석, 에러 해결 방법 등
편	산만하고 복잡한 자료를 편집해 질서를 부여한 것	프로그램 설치/설정 방법, 튜토리얼, 세미나 후기, 책 리뷰
집	여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것	명령어 모음, 팁, OO가지 규칙

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

Ref. 네이버 기술 블로그

[기본 구성]
1. 머리말
 가. 서비스 설명
 나. 개발의 필요성
2. 본문
 가. 아키텍처나 알고리즘
 나. 개발 모델(최종 루트)
 다. 개발 과정에서 발견한 문제와 해결 방법(경험 루트)
 라. 남은 작업
3. 맺음말
 가. 소감이나 회고
// 작성 순서: 본문 > 맺음말 > 머리말

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

기술 블로그를 쓰는 개발자는 '경전'을 쓰는 사람이 아니라 경전을 자기 방식으로 풀이하는 사람이다.

Ref 1. 박시홍님이 쓴 "GET과 POST의 차이"

Ref 2. 카카오 기술 블로그, "MySQL Ascending index vs Descending index"

03_글의 종류별로 목차 잡는 법 II - 편집

| 편: 순서를 요약하여 쓰자

> 시간 순서로 하나씩 나열해 내용을 쓴 다음, 단계로 묶어서 요약하면 끝

Ref. 네이버 기술 블로그, "간단하게 구축해보는 JavaScript 개발 환경"

| 집: 글쓰기가 두렵다면 자룔르 모아 핵심을 엮어서 쓰자

Ref. "13 Simple Rules for Good Coding"

04_기업의 기술 블로그 운영 팁

기술 블로그는 회사의 가치를 높인다

기술 블로그도 투자를 해야 살아난다

개발자의 글쓰기는 회사의 문화를 반영한다

Ref 1. 네이버 기술 블로그

Ref 2. 우아한형제들 기술 블로그

협업해서 글쓰기, 짝 글쓰기를 해보자

 

[에필로그] 회사가 개발자 글쓰기 교육을 하자

개발자의 글쓰기 교육 체계

기본 과정(2일 16시간)

전문 과정 A. 수주를 돕는 SI 제안서 작성(1일 8시간)

전문 과정 B. 기술 블로그 작성(1일 8시간)

관리자 과정(1회 4시간 3주 코스)

---

여기에 서술한 내용은 모두 '개발자의 글쓰기'에서 발췌한 내용입니다. 초보 개발자로써 제게 와닿았던 부분 나중이라도 한번 보면 좋겠다 싶은 부분만 추렸습니다. 해당 책은 초, 중, 고급 개발자들에게 모두 도움이 될만한 책으로 개발자에게 있어 '수학의 정석' 같은 느낌을 주었습니다. 개발자라면 책장에 하나쯤은 구비해두고, 필요할 때마다 참고하면 좋을 듯 싶습니다.

오늘도 그럼 감사합니다. ^^