<개발자의 글쓰기>

연방방·2023년 4월 6일

프롤로그

개발자의 글쓰기 특징

정확성: 틀림이 없어 확실한 것을 의미
간결성: 글에 군더더기가 없고 깔끔한 것을 의미
가독성: 쉽게 읽히는 것을 의미

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

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

문장을 구조화하는 법

// before
색상 RGB 값을 각각 사용하기 때문에 입력 데이터는 3차원 벡터이다.

// after
입력 데이터는 3차원 데이터이다. 색상 RGB 값을 각각 사용하기 때문이다.

문장을 쉽게 쓰려면 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다.

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

개발자의 생각을 글로 표현하는 방식
- 서술식
- 개조식
- 도식
중요한 것은 내용과 형식이 일치해야 한다.
- 줄거리가 있는 설명이나 이야기는 서술식으로 써야 함
- 여러 가지 종류의 항목과 내용이 반복되거나 서술식에서 강조가 필요한 내용으로 개조식을 써야 함
- 각 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식으로 써야 함

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

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

파스칼 표기법으로 클래스 이름 짓기
- 클래스의 첫 글자는 어디에 위치하든 모두 대문자로 쓴다.
카멜 표기법으로 함수, 변수의 이름 짓기
- 카멜 표기법은 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓴다.
- 주로 함수나 변수에 사용합니다.
- 함수는 동작을 시키는 명령어 개념이므로 첫 단어가 주로 동사입니다. 변수는 형용사로 시작하는 경우도 많다.
상수는 모두 대문자로 쓴다
- 상수는 값이 변해서는 안된다는 점을 강조하고 주의하기 위해서 대문자를 선택했다.
- 회사 안에서는 통일하는 것이 좋다.
패키지와 모듈은 모두 소문자로 쓴다
- 패키지와 모듈은 클래스와 함수보다 더 높은 위치다. 그러나 소문자로만 쓴다.
- 이유는 패키지와모듈이 클래스를 모으거나 함수를 담아놓는 통이기 때문이다.
- 실용적인 이유는 패키지 이름과 클래스 이름을 혼동할 수 있고, 모듈 이름과 함수 이름을 헷갈릴 수 있어서 이가 컨벤션이 되었다.
BEM 표기법
- CSS에서 사용하는 BEM(Block, Element, Modifier) 표기법은 '대상__요소--상태'를 의미한다.
- 대상의 요소나 부분을 의미할 때는 언더스코어 두 개(__)로 연결한다.
- 대상이나 요소의 상태나 속성을 의미할 때는 하이픈 두개(--)로 연결한다.

변수 이름을 잘 짓는 법

i는 변수 이름이지만 d는 아니다
- 가장 많이 쓰는 변수 이름은 i, LOG, result
- 좌푯값으로 x, y도 괜찮다.
- day는 일자의 의미를 사용하지만, 임의의 날은 someday, 오늘은 today, 특정한 날은 thisDay, 마지막 날은 finalDay를 사용하는 것이 좋다.
긴 이름? 짧은 이름? 검색 잘 되는 이름!
- 과거에는 헝가리안 표기법이 유익했으나 현재는 변수 타입이 자동이 되었기 때문에 레거시가 되었다.
복수형을 나타내는 s를 붙일까 말까?
- 배열에 s를 붙이는 방법과 array와 list of를 쓰는 것이 나을 수도 있다.
약어를 쓰는 것이 좋을가? 안 쓰는 것이 좋을까?
- 약어를 사용하는 기준은 보편성이 되어야 한다.
- 회사나 업계에서 많이 사용하는 약어라면 코드에 사용하는 것이 좋다.
중요한 단어를 앞에 쓴다
- 중요한 것이 앞에 와야합니다.
- int totalVisitor 보다는 int visitorTotal
함수 이름 짓는 순서
- 불필요한 단어를 제외하는 것이 중요하다.
- 1함수 1업무 규칙을 적용하고, 묶을 수 있는 것은 묶어야 한다.
- 다음의 순서로 진행할 수 있다.

1. 사용자 이름을 input 태그에서 가져옵니다.
2. 사용자 이름의 글자 수를 확인합니다.
3. 입력이 안되었으면 input 태그를 활성화합니다.
4. 글자 수가 한글 두 글자 이하면 확인을 요청합니다.

// 1번과 2번~4번으로 묶을 수 있는 구조다.

1. (함수1) 사용자 이름을 input 태그에서 가져옵니다.
2. (함수2) 사용자 이름의 글자 수가 2글자 이하면 다음과 같이 처리합니다.
    - 만약 글자 수가 0이면, 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는 앞뒤 단어를 바꾼다. 소유격도 바꾼다.
// 띄어쓰기도 없애고, 첫 철자를 대문자로 바꾼다.
// 함수를 사용할 때 의미상 없어도 되는 단어는 없앤다.

(함수 1) getUserNameFromField()
(함수 2) checkUserNameUnder2Characters()

좋은 이름의 기준, SMART

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

좋은 이름인지를 확인하는 5가지 기준을 SMART
- easy to Search: 검색하기 쉽게
- easy to Mix: 조합하기 쉽게
- easy to Agree: 수긍하기 쉽게
- easy to Remember: 기억하기 쉽게
- easy to Type: 입력하기 쉽게
easy to Search: 검색하기 쉽게 이름 짓는 법
- 검색하기 쉬운 이름은 고전적 범주화를 이용해 한 단계상위 범주의 이름을 태그처럼 덧붙이면 된다.

// 나쁜 예
SERVER_TIMEOUT
NO_RESULT
BAD_REQUEST
SERVER_ALLOWED_REQUESTS_EXCESS

// 좋은 예
ERROR_SERVER_TIMEOUT
ERROR_NO_RESULT
ERROR_BAD_REQUEST
ERROR_SERVER_ALLOWED_REQUESTS_EXCESS

user
userBuyer
userPayer
userRegister
userRegisterButNoPayer

(회사의 네이밍 컨벤션에 위배되지 않는지 먼저 따져 본 뒤 사용해야 한다.)

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

이름을 잘 지으면 주석을 줄일 수 있다
처음부터 주석 없이 코딩하는 연습을 하자

3장. 사용자와 소통하는 에러 메세지 쓰기

사용자 에러 메세지

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

개발자는 사용자 에러가 발생하면 알림창을 이용해 에러가 발생했음을 알려주는 메시지를 보여줘서, 바른 행동을 유도한다.
오류의 내용과 오류의 원인을 함께 알려줘야 사용자가 대처할 수 있다.
즉, 사용자 에러 메시지에는 에러의 내용, 에러의 원인, 에러의 해결 방법이 포함되어야 한다.
- 에러 내용: 오류로 인한 문제와 종류
- 에러의 원인: 오류를 발생시킨 직접적이고 근본적인 원인
- 에러 해결 방법: 사용자가 오류를 해결할 가장 쉽고 빠른 방법

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

에러 내용이나 원인을 먼저 구구절절 말하는 것보다는 해결하는 방법을 먼저 얘기하는 편이 사용자에게 낫다.
- [에러 해결 방법]
- [에러 원인]
- [에러 내용]]
종종 원인과 내용이 합쳐서 쓰다보면 문장이 매끄럽지 않은 경우가 발생합니다. 이때는 원인만 간단히 써도 된다.

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

에러 메시지가 헷갈리는 경우인 경우, 사용자 입장에서는 선택이 어려울 수 있다.
행동에 만 집중하면 오해를 없앨 수 있다.

// bad case
지금 이 페이지를 떠나면 편집한 내용이 취소될 수 있습니다. 취소하시겠습니까? 예/아니오

// not bad case
편집한 내용을 삭제하고 다른 페이지로 이동하시겠습니까? 예/아니오

// good case
편집한 내용을 삭제하고 다른 페이지로 이동하시겠습니까? 삭제하고 이동하기/계속 편집하기

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

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

에러를 줄이려면 개발자도 사용자의 사용 방식을 이해해야 한다.
대표적인 예시로, 달력 예약시 이전 날짜 선택이 불가능하게 한다.

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

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

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

일을 하고 상사나 고객에게 글로 보고해야 할 때가 있다. 이때 글을 줄이면 일을 안한 것처럼 보인다.
반대로, 너무 많이 쓰면 이또한 좋지 않다.
적절한 양으로 쓰는 것이 중요합니다.

1단계: 선정하기

체인지 로그 중에서 쓸 것과 없앨 것을 구분하는 것이 중요하다.

		개발자가
		노력을 많이 들인것	노력을 덜 들인 것
독자가	관심 있는 것	1순위	2순위
	관심 없는 것	3순위	4순위

2단계: 분류하기

비슷한 체인지 로그를 선정했으면 비스한 체인지 로그까지 묶어야 한다.

첫번째 방법: 개발 관점에서 비슷한 작업을 묶는 방법

새로운 기능 추가
- 닉네임 만들 때 특수 문자를 입력하는 기능 추가
- 빈 게임방을 자동으로 검색하는 기능 추가

기능 개선
- 용량 큰 사진 추가시, 휴대전화 메모리를 최소화하도록 등록 방식을 개선
- 최근 기록이 상위에 올라오도록 개선
- 게임 종료 후 바로 순위를 볼 수 있도록 개선

오류 수정
- 고해상도 폰에서 아이콘이 찌그러지는 오류 수정
- 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류 수정
- 애니메이션 스티커가 갑자기 멈추는 오류 수정
- 미리 보기에서 간혹 리부팅되는 문제를 해결

두 번째 방법: 독자가 일반 사용자인 경우에 유용하며, 사용자 관점에서 비슷한 것끼리 묶는 방법

게임 준비
- 미리 보기에서 간혹 리부팅되는 문제를 해결
- 빈 게임방을 자동으로 검색하는 기능 추가
- 닉네임 만들 때 특수 문자를 입력하는 기능 추가

게임 중
- 고해상도 폰에서 아이콘이 찌그러지는 오류 수정
- 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류 수정
- 애니메이션 스티커가 갑자기 멈추는 오류 수정

게임 종료
- 최근 기록이 상위에 올라오도록 개선
- 게임 종료 후 바로 순위를 볼 수 있도록 개선
- 용량 큰 사진 추가시, 휴대전화 메모리를 최소화하도록 등록 방식을 개선

3단계: 요약하기

체인지 로그로 분류하면 문장 단위로 요약
요약 방법 중에서 서술식 문장을 개조식 문장으로 만들면 더 자연스럽다.

게임 준비
- 미리 보기 리부팅 문제 해결
- 빈 게임방 자동 검색 기능 추가
- 닉네임 만들 때 특수 문자 입력 기능 추가

게임 중
- 고해상도 폰에서 아이콘이 찌그러지는 오류 수정
- 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류 수정
- 애니메이션 스티커 멈추는 오류 수정

게임 종료
- 최근 기록이 상위에 올라오도록 개선
- 게임 종료 후 바로 순위를 볼 수 있도록 개선
- 용량 큰 사진 등록할 때 휴대전화 메모리 최소화

4단계: 종합하기

위의 릴리스 내용 전체를 종합해서 한 문장으로 만들어서, 작성해야 한다.
전체를 종합하는 방법은 분석과 반대이다.
위를 종합하면 다음과 같은 형태로 만들 수 있다.

시간 절감, 다양한 닉네임, 정확한 사용, 결과를 쉽게 확인, 결과를 빠르게 확인, 편안한 마음으로 서비스 이용

이를 한 문장으로 만들려면, 핵심이 되는 것을 발췌해야하며 앞의 1순위 방법을 사용해야 한다.

게임방에 더 빨리 입장하고 게임 결과를 바로 확인할 수 있도록 다음과 같이 변경

사용자 편리성 개선
- 게임방에 더 빨리 입장
- 게임 결과 바로 확인

[세부 내용]
- 게임 준비
- 미리 보기 리부팅 문제 해결
- 빈 게임방 자동 검색 기능 추가
- 닉네임 만들 때 특수 문자 입력 기능 추가

게임 중
- 고해상도 폰에서 아이콘이 찌그러지는 오류 수정
- 가로/세로 화면 전환 시 하단 메뉴가 사라지는 오류 수정
- 애니메이션 스티커 멈추는 오류 수정

게임 종료
- 최근 기록이 상위에 올라오도록 개선
- 게임 종료 후 바로 순위를 볼 수 있도록 개선
- 용량 큰 사진 등록할 때 휴대전화 메모리 최소화

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

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

범주, 용도, 특징

서비스 메뉴얼이나 개발 가이드의 첫 문단은 서비스 개념을 설명하는 자리다.
개발자가 독자에게 서비스 개념을 설명할 때는 범주, 용도, 특징 순으로 쓰는 것이 좋다.

(범주) Amazon Simple Storage Service(Amazon S3)는 인터넷 스토리지 서비스입니다.
(용도) Amzaon S3를 사용하면 인터넷을 통해 언제 어디서든 원하는 양의 데이터를 저장하고 검색할 수 있습니다.
(특징) AWS Management Console의 간단하고 직관적인 웹 인터페이스를 통해 이러한 작업을 수행할 수 있습니다.

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

범주는 서비스를 소개하거나 설명하는 첫 문장인 만큼 정확하고 적절하게 정해야 한다.
가장 좋은 방법은 여러 경쟁사가 사용하는 보편적인 서비스 범주를 따라 하는 것이다.

ex) ABC는 크라우드펀딩 서비스입니다.

경쟁사보다 전반적으로 발전한 서비스라면
- ABC는 보다 발전된 크라우드펀딩 서비스입니다.

특정 사용자를 위한 서비스라면
- ABC는 개발자를 위한 크라우드펀딩 서비스입니다.

개발자가 유명하거나 공공성을 강조하고 싶다면
- ABC는 NAVER가 개발하고 운영하는 크라우드펀딩 서비스입니다.

새로운 범주를 만들고 싶다면
- ABC는 크라우드옥션 서비스입니다.
- 마켓팅에 관심이 있거나 스타트업 대표를 겸하는 개발자라면 서비스의 범주를 신중하게 정해야 합니다.

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

첫 문단의 첫 문장에 범주가 사용된다면 두번째 문장은 독자 관점의 용도를 주로 적는다.
용도는 독자가 이 서비스를 이용하는 이유다.
범주의 핵심 기능을 용도로 설명함으로써 독자의 머릿속에 서비스의 정체성을 명확히 심을 수 있다.

// 좋은 예시
인공지능 플랫폼은 사용자의 요구를 인식하여 인공지능으로 분석해서 사용자가 원하는 정보나 서비스를 제공합니다.

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

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

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

소재 우선 글쓰기는 주제 의식이 아니라 소재 의식을 갖고 쓰는 것이다.
소재 의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 생각이나 해결 방안을 뜻한다.
주제 의식은 많은 사람에게 보편적인 주제를 선택해서 많은 사람에게 퍼뜨리는 것이지만 소재 의식은 독자와 상관없이 대상이나 상황에 대해 있었던 일을 이야기를 하는 것이다.

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

개발자가 기술 블로그를 쓸 때는 독자를 생각해서 어려운 용어를 일부로 해석하거나 쉬운 용어로 바꿀 필요가 없다.
- 필요하면 링크를 걸어둔다.
기술 블로그는 실력이 비슷한 독자를 위한 것이다.

셋째, 재미있게 글을 쓰자

글쓰기 기교는 글을 아름답게 만들고 쉽게 읽히게 해야한다.
경험과 기교를 녹여서 쓰는 것이 좋다.

글의 종류별로 목차 잡는 법

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

4가지 종류별로 글의 목차를 구조화할 수 있다.

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

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

저는 직접 경험한 것을 쓰는 것
개발기의 목차는 1차원 단방향이다.
개발자가 가장 잘 쓸 수 있는 내용은 본문이다. 목차를 정하면 머리말부터 쓰지 말고 본문부터 쓰는 것이 좋다.

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

술은 어떤 것을 분석해 의미를 풀이하고 해석한 것
개발에서 술은 새로운 기술을 자세하게 또는 비유해 설명한 것이다. 비슷한 용어를 비교해 풀이한 것, 에러 해결 방법 등이 여기에 해당된다.
기술 블로그를 쓰는 개발자는 '경전'을 쓰는 사람이 아니라 경전을 자기 방식으로 풀이하는 사람이다.

편: 순서를 요약하여 쓰자

편은 산만하고 복잡한 자료를 편집해 질서를 부여한 것
편은 시간 순서로 하나씩 나열해 내용을 쓴 다음, 단계로 묶어서 요약하면 글이 완성된다.
글을 쓸 때는 한 일을 먼저 시간 순서로 적은 다음, 내용을 다 적는다. 그 후 단계를 만들어서 묶은 뒤 하위 내용을 간략히 요약한다.
우선적으로 구조를 생각하지 않고 한 일을 나열 하는 것이 진도가 많이 나간다.

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

집은 여러 사람의 견해나 흩어진 자료를 한데 모아 정리하는 것
집은 내용을 많이 쓰는 것이 아니라 핵심만 간결하게 정리한 것
집이라고 반드시 여러 사람의 견해를 넣을 필요 없이, 본인의 경험에서 터특한 것을 핵심만 정리해서 나열해도 좋다.
기술 블로그에서 가장 쉽게 도전할 수 있는 글이 집이고 그 다음이 편이다.

연방방

이전 포스트

.GIF가 .MP4보다 파일 크기가 큰 이유(feat. 이미지 렌더링)

다음 포스트