[Book] 개발자의 글쓰기 _김철수著

▒ 책 정보

 

개발자의 글쓰기

이 책은 개발자의 글쓰기 능력을 종합적으로 향상하기 위한 책이다. 코드 안에서는 함수와 변수 이름을 짓는 것부터 주석 쓰는 법, 에러 메시지 쓰는 법까지 알려준다. 코드 밖에서는 릴리스 노트, 장애 보고서, 개발 가이드를 어떻게 하면 잘 쓸 수 있는지를 알려준다. 외주 개발을 하는 개발자를 위해 SI 제안서의 기술 부문을 설득력 있게 쓰는 법도 놓치지 않았다. 블로그를 운영하려는 개발자나 IT기업을 위해 기술 블로그를 쓰는 법과 운영하는 팁도 담았다.

 

저자

김철수

출판

위키북스

출판일

2019.10.04

 

 

 개발자에게 요구되는 글쓰기 능력은 통상적인 글쓰기에서의 그것과 다르다.

그러나 정작 개발자에게 필요한 글쓰기에 대해 다룬 정보는 많지 않다.

 

이 책은 개발과정에 있어서 가장 기본이라 할 수 있는 변수 이름 짓기, 네이밍 컨벤션 부터 시작해서 에러 메시지, 릴리즈노트, 장애 보고서, 개발 가이드, SI 제안서, 기술 블로그 같이 보다 복합적인 주제들을 다루는 방법에 이르기까지 개발자를 위한 실용적인 글쓰기 정보들을 담았다.

 

▒ 1장_ 개발자가 알아야 할 글쓰기의 기본

• 조사, 순서, 숫자, 하다, 기호만 붙이고 나머지는 띄어쓴다.
•  반대되는 영어단어 사용시 대칭되는 단어를 선택한다.

show-hide
visible - invisible 등

• 유사한 의미의 단어 사용시 의미를 구분한다.

stop(잠시중단)
end(완전한 중단)
finish(end와 유사하나 보다 종국적 의미)
pause(일시적 중단 - 재시작 가능성 높음)
suspend(다음단계로의 진행을 중단)
hold(어떤 의도가 부여된 중단)

• 부여되는 기능을 구분해서 사용한다.
• 중요한 것은 얼마나 일관성 있게, 개연성 있게 사용하느냐의 여부이다.

get류 함수
get은 어떤 값을 받아내는 함수이름에 사용
return은 주로  함수 안의 제어에 쓰이기 때문에 함수 이름에 쓰지않음
retrieve는 get과 비슷한 목적을 가지나, search의 뉘앙스를 내포함
acquire는 다른 함수에게 배타적인 독점적 위치를 갖음을 의미
fetch는 현재 값을 가리키는 포인터가 다음 값으로 이동한 것을 가져온다는 뜻.

set류 함수(변경, 설정의 의미)
init 초기화 설정
create 틀 자체를 만들 때 사용
register 기존의 틀에 값을 입력하는 개념.

change류 함수
change : 단순한 내용 변경
modify: 잘못된 것을 바로잡음 
revise: 기존에 없던 새로운 개념을 덧붙임

parameter는 매개변수로서, 함수에 정의한 변수variable을 의미. 
argument는 전달인자로, 함수를 호출할 때 전달되는 값을 의미.
attribute는 마크업 언어에서 속성값을 의미하며 property로 쓰이기도 함.

must는 필수요구사항을, should는 권고사항을.
행동을 반영한 함수를 do로 통칭하기도 함.
boolean값을 반환하는 함수라면 is나 does를 사용하기도..

 

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

 

• 이름 짓기는 창조가 아니라 재조합이다. 짬뽕과 짜장면을 합쳐 짬짜면이라 명명하는 것과 같다.
• - 클래스는 UpperCamelCase(=파스칼표기법)
  - 함수와 변수는 lowerCamelCas
  - 상수는 UPPER_DELIMITER_CASE(변수와 구별하기 위함)
  - 패키지나 모듈은 모두 소문자(단순한 경로에 불과하기 때문)
  - BEM표기법(CSS에서 사용) => 대상_요소--상태(form_button-disabled)
• i는 integer나 index를 의미하기에 직관적이다
  그러나 d는 아니다. day일수도, date일수도, double일수도 있다.
  day도 today,someday,thisday등등 다양한 의미를 내포할 수 있기에 의미에 유의한다

 

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

 

• 깨진링크를 찾아내는 서비스를 적극 활용하자.

브로큰링크체크닷컴(https://www.brokenlinkcheck.com)
구글 서치콘솔(https://www.google.com/webmasters/tools/)

• 개발자가 사용자를 불완전한 존재로 인식한다면,  사용자의 모든행동을 검증하여 경고로 대응한다. 이는 시스템의 불안전을 유발한다. 이것은 결국 개발 철학의 문제이며, 개발자는 자신만의 개발철학을 가져야 한다.
• 인터넷뱅킹 사이트에서 비밀번호 입력오류시 잔여횟수를 표시하는 것과 같이 메시지를 구조화한다면 에러메시지를 최소화 할 수 있다.
• 에러메시지에서는 에러내용/에러의원인/에러 해결방법을 간결하게 전달한다.

 

▒ 그 외_

 

이하 챕터는 요약 생략.

내 수준에서는 가볍게 읽어보고 넘어가는 것으로 족할듯.

4장_독자의 관점에서 릴리스 문서와 장애 보고서 쓰기
5장_설명, 묘사, 논증, 서사로 개발가이드 쓰기
6장_수주를 돕는 SI제안서 쓰기
7장_기술 블로그 쉽게 쓰고 운영하기