개발자의 글쓰기를 읽고

목차

요약

코딩이나 프로그래밍에서 기독성과 소통을 고민하고 있었다면 꼭 읽어봐야할 책! 코딩뿐만아니라 테크니컬 및 일반적인 글쓰기에도 큰 도움이된다!

1.추천하는 이유

  • 이해해하기 쉬운 글구조
  • 다양한 예제와 자세한 설명

2.아쉬운 점

  • 직접 시도해볼 수는 간단한 문제코너가 있었어도 좋았을 것 같다.

3.Yes24 ebook 읽어보기

왜 이책을 읽게 되었는가?

이번에 새로 블로그를 시작하면서 기술적인 글쓰기에 어떻게 시작해야할지 고민이 있었고, 이를 타개하기 위해서 이 책을 읽게 되었다. 또 상수나 여러 코딩쪽 요소들에 대한 내용들도 고민이었기에 바로 책을 고를 수 있었다.

결론

혼자서 코딩을 하다보면 변수나 상수이름을 규칙없이 만들어서 나중에 다시 쓰기 불편할 때가 많은데, 책에서 배운 내용을 바탕으로 규칙을 정하고 만들면 시간이 흐른다음이나 다른 사람에게 설명할때도 훨씬 편한 것 같아서 기대가된다. 그 중 몇가지 자주 쓸 것 같은 내용을 정리해보자면 다음과 같다.

  • 큰 따옴표는 문자열에, 작은 따옴표는 단일문자에 사용한다.
1
2
char str[] = "Hello world";
str[0] = 'A';
  • 영어 대문자 표기원칙

  • 중요하건 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로 쓴다.

  • 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 쓴다.

  • 명사나 관사가 아닌 동사, 형용사 등은 소문자를 쓴다.

파스칼 표기법 -> 모든 단어에서 첫 글자를 대문자로 쓰는 방식(주로 클래스 이름에 사용)

1
2
interface Menu
class CoffeeMenu implements Menu()

카멜 표기법 -> 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓴다.(주로 함수와 변수에 사용한다.)

1
2
3
4
int totalCount = 1;
function orderCoffee(){
console.log("One Americano with " + totalCount + "cream");
}

상수는 모두 대문자와 언더스코어로 단어를 연결한다.

1
static final int COFFFEE_MAX = 10;

패캐지와 모듈은 모두 소문자로 쓴다.

1
2
kr.co.wikibook.android.developerwriting
import developerwriting

BEM 표기법 -> 대상__요소–상태로 표현한다.(대상의 요소나 부분을 의미할때는 언더스코어 두 개/대상이나 요소의 상태나 속성을 의미할 때는 하이픈 두 개로 연결한다.)

1
2
3
.form{}
.form__button {}
.form__button--disabled {}
  • 긴 이름, 잛은 이름이 아닌 검색이 잘 되는 이름을 사용하자

헝가리안 표기법은 이제 과거의 유산이다!

복수의 의미가 담긴 함수명은 -s보다는 array, list of를 사용하자

1
function checkListofCoffeeTypeInDB()

약어는 서비스 이름,패키지 이름, 또는 클래스 이름에 사용한다.

중요한 단어를 앞으로 배치해서 변수 이름을 만들자

1
2
3
int visitorTotal
int registerTotal
int salesOfThisMonthTotal

1함수 1업무 규칙

풍선인형은 영어로 어떻게 불러야할까? 유튜브라는 이름은 어떻게 생겼을까?

Search / Mix / Agree / Remember / Type (SMART) 검색하기, 조합하기, 수긍하기, 기억하기, 입력하기 쉬워야한다.

고전적 범주화 -> 큰 범주를 먼저써서 검색하기 쉽게하자 혹시라도 항목이 너무 많다면 범주를 놓고 나누는 걸 먼저하자!

1
2
const ERROR_SERVER_TIMEOUT
const ERROR_BAD_REQUEST
  • 객관적인 표현과 주관적인 표현은 분리해서 사용하자

의견을 근거와 함께 쓰자.

개발가이드는 거칠게도,공손하게도 쓰지말자 -> 개발가이드내에서는 여지를 남기면 안된다.

주장을 했으면 이유를 바로 말하자! (강아지 혼내듯이)

문제와 답을 붙여서 쓰자(과정을 길게 이어서 쓰지말자)

메뉴얼에서는 서사식으로 전개하되 단계와 단계의 목적을 정리하자

글쓰기의 계획 단계

  1. 이 글을 왜 쓰는가?
  2. 이 글을 읽는 독자는 누구인가?
  3. 이 글을 읽는 독자에게 무엇을 말하려고 하는가?
  4. 이 글이 주장하는 바가 무엇인가?
  5. 이 글이 주장하는 바의 근거가 분명한가?

개발 글쓰기

  1. 소재 우선 글쓰기 -> 케이스에 중심적으로 글을 쓰자
  2. 자기 수준 글쓰기 -> 더 자세한 설명은 링크를 활용하자
  3. 재미있는 글쓰기 -> 경험을 바탕으로 공감하고 끄덕이게만들자

저.술.편.집

  1. 저 -> 직접 실험하고 경험한 과정이나 결과
  2. 술 -> 어떤 것을 분석하여 의미를 풀이하고 해석한 것
  3. 편 -> 산만하고 복잡한 자료를 편집해 질서를 부여한 것
  4. 집 -> 여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것

(저)

목차를 정하고 본문부터 써보자 -> (2차원 -> 1차원 / 성공한 루트와 실패한 루트를 구별하자)

네이버 기술블로그를 참고하자!

(술)

기술의 자세하게 또는 비유해 설명한 것, 비슷한 용어를 비교해 풀이한 것, 에러 해결 방법

경전을 자기방식으로 풀이하는 개발자!

(편)

프로그램 설치, 개발방법, 튜토리얼 등

시간 순서대로 정리 -> 단계로 서순으로 정리한 내용을 다시 정리

(집)

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

명령어 모음, 팁, 00가지 규칙

네이버와 우아한형제들의 기술블로그

중요하게 생각했던 내용들

개발자 글쓰기의 특징

  1. 정확성/틀림없이 확실한 것
  2. 간결성/간단하고 깔끔한 것 WITH 핵심
  3. 가독성/쉽게 읽히는 것

하지만 서로 대치되는 특성들! 정확도를 높이면 간결성과 가독성이 떨어진다.

간단히 쓰는 법 예시/ 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 한다.

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

이제 주어를 앞으로 보내자

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

이제 인과관계를 나누어서 두 문장으로 나누자

입력데이터는 색상 RGB 값을 각각 사용한다. 그래서 입력데이터는 3차원 벡터이다.

이제 핵심 내용을 쓰고 뒤에 부연설명을 붙인다.

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

정리 끝!

글쓰기 방법의 차이

  1. 서술식 -> 무엇을 논증하거나 설명할때 사용
  2. 개조식 -> 헤드라인을 쓰거나 어떤 사항을 나열할때 사용
  3. 도식 -> 사물의 구조나 관계, 상태를 그림이나 서식으로 보여줄때 사용 -> 표를 사용하자!
  • 줄거리가 있는 설명이나 이야기는 서술식으로
  • 항목이나 내용이 반복되거나 강조가 필요하면 개조식으로
  • 항목이나 관계를 명확히 규정하고 싶다면 도식으로!

급이 높은 문장과 낮은 문장은 구별된다./탭이나 스타일로 일정하게 정리하자/높은 곳의 자리는 낮은 곳의 자리보다 크고 고급스럽다. -> 계층을 문단 디자인으로 나타내자 -> 글에 위치와 계층을 표현하자

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

좋은 함수의 예시

1
English(word1, word2);

네이버 블로그나 브런치로 맞춤법을 점검하자?

큰 따옴표는 문자열에, 작은 따옴표는 단일문자에 사용한다.

1
2
char str[] = "Hello world";
str[0] = 'A';

큰 따옴표는 글에 직접 대화를 표시하거나 말,글을 인용하는데 사용한다. 작은 따옴표는 인용안에 인용말이나 마음속으로 한말을 표현한다.

영어의 비슷한 말과 반대되는 말을 잘 골라서 사용하자(finish 끝을 본 상태, hold는 유보한 상태)

영어 단어 사용 -> 이미 굳어진 외래어는 관용을 존중한되, 그 범위와 용례는 따로 정한다.

변수 이름 짓기는 창조가 아닌 조합(짬자면처럼 이름을 조합하자!)

네이밍 컨벤션! 통계적으로 17글자,3단어로 구성

영어 대문자 표기원칙

  1. 중요하건 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로 쓴다.
  2. 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 쓴다.
  3. 명사나 관사가 아닌 동사, 형용사 등은 소문자를 쓴다.

파스칼 표기법 -> 모든 단어에서 첫 글자를 대문자로 쓰는 방식(주로 클래스 이름에 사용)

1
2
interface Menu
class CoffeeMenu implements Menu()

카멜 표기법 -> 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓴다.(주로 함수와 변수에 사용한다.)

1
2
3
4
int totalCount = 1;
function orderCoffee(){
console.log("One Americano with " + totalCount + "cream");
}

상수는 모두 대문자와 언더스코어로 단어를 연결한다.

1
static final int COFFFEE_MAX = 10;

패캐지와 모듈은 모두 소문자로 쓴다.

1
2
kr.co.wikibook.android.developerwriting
import developerwriting

BEM 표기법 -> 대상__요소–상태로 표현한다.(대상의 요소나 부분을 의미할때는 언더스코어 두 개/대상이나 요소의 상태나 속성을 의미할 때는 하이픈 두 개로 연결한다.)

1
2
3
.form{}
.form__button {}
.form__button--disabled {}

기독성과 소통이 먼저다 -> 협력을 위하여!

i,j,k는 변수 이름이지만, d는 아니다.

1
2
3
4
5
6
7
int someday
int today
int thisMonth
int finalYear
int daysSinceCreated
int monthSinceUpdated
int yearsSinceRegistered

긴 이름, 잛은 이름이 아닌 검색이 잘 되는 이름을 사용하자

헝가리안 표기법은 이제 과거의 유산이다!

복수의 의미가 담긴 함수명은 -s보다는 array, list of를 사용하자

1
function checkListofCoffeeTypeInDB()

약어는 서비스 이름,패키지 이름, 또는 클래스 이름에 사용한다.

중요한 단어를 앞으로 배치해서 변수 이름을 만들자

1
2
3
int visitorTotal
int registerTotal
int salesOfThisMonthTotal

1함수 1업무 규칙

풍선인형은 영어로 어떻게 불러야할까? 유튜브라는 이름은 어떻게 생겼을까?

Search / Mix / Agree / Remember / Type (SMART) 검색하기, 조합하기, 수긍하기, 기억하기, 입력하기 쉬워야한다.

고전적 범주화 -> 큰 범주를 먼저써서 검색하기 쉽게하자 혹시라도 항목이 너무 많다면 범주를 놓고 나누는 걸 먼저하자!

1
2
const ERROR_SERVER_TIMEOUT
const ERROR_BAD_REQUEST

조합하기 쉬운 구조로 만들자! -> 쉽게 수정할 수 있는 코드를 쓰자

1
2
3
4
5
6
7
8
9
10
11
12
<html>
<head>
<style>
h1.title { font-size : 2em}
h2.title { font-size : 4em}
</style>
</head>
<body>
<h1 class="title">커피 좋아</h1>
<h2 class="title">너무 좋아</h2>
</body>
</html>

논리적 정합성이 아닌 상황에 마땅한 이름을 사용하자! -> 효율적인 이름을 사용하자

감각적인 단어로 기억하기 쉬운 이름을 짓자, 다만 보편적인 이름은 그대로 사용하자

오탈자를 고려해서 치기쉽고, 발음대로 쓸 수 있고, 간단하게 정하자

이름이 주석이 할 일을 대신할 수 있도록하자!

1
2
int h = 480 //h가 어떤 변수인지를 설명해야하는 주석이 필요하다
int screenHeightMax = 480 //이렇게하면 어떤 변수인지 바로 알 수 있다.

주석은 많아도 적어도 괜찮다! 같은 개발자들이 코드를 이해할 수 있게만 적으면 된다.!

주석도 코드다! -> 코드처럼 주석을 리뷰하자!

깨진 링크가 없도록하자!

에러나 콘솔내용은 구체적으로 쓰자

‘아니요-예’ 같은 레이아웃은 프로그램내에서 통일하자

사용자의 사용 방식을 이해하자

에러메세지를 예방메세지로 활용하자 -> 비즈니스 메세지

로그 정리하기 -> 일단은 최대한 많이 쓴다.

  1. 선정하기 -> 각자가 듣고 싶은 내용은 다르다.
  2. 분류하기 -> 비슷한 내용끼리 묶는다.
  3. 요약하기 -> 서술식 문장을 개조식으로 묶는다. 부사와 형용사,조사나 어미를 없애고 정확하고 적절한 단어로 대체한다.
  4. 종합하기
    • 종합과 분석은 반대다.
    • 종합은 특성과 결과를 섞어서 말한다.
  5. 다른 앱들의 체인지로그도 읽어보자

Semantic Versioning(유의적 버전) -> X(예전이랑호환이 안될 정도로 큰 패치),Y(새로운 기능 추가),Z(작은 패치들)

릴리스 노트에는 으로 구성된다.

  1. 문제 상황
  2. 문제점
  3. 해결책
  4. 후속 계획

릴리스 노트의 3가지의 어투

  1. 필수 -> “해야한다/해서는 안된다.
  2. 권장 -> “하는 것이 좋다/이상적이다.”
  3. 선택 -> “할 수도 있다./하는 방법이 있다.”

장애보고서 쓰기

  1. 질문에 대답하는 신속한 글쓰기
  2. 원인과 이유를 찾는 분석적 글쓰기
  3. 상사를 고려하는 비즈니스 관점의 글쓰기
  4. 원하는 것을 얻는 정치적 글쓰기
  5. 들어가야하는 내용들
    • 장애 내용
    • 장애 영향
    • 장애 원인
    • 조치 상황
    • 조치 결과
    • 핵심 원인
    • 향후 대책

5why 기법 -> 이유를 5번 물어, 근본적인 원인을 찾아라

가진게 망치뿐이면 모든 것이 못으로 보인다.

퍼센트 말하기

서비스를 설명하자(ex.AWS S3)

  1. 범주 -> S3는 인터넷 스토리지 서비스입니다.
  2. 용도 -> 언제든지 원하는 양의 데이터를 저장하고 찾을 수 있습니다.
  3. 특징 -> 아마존 서비스와 연동해서 간단하고 직관적으로 웹 인터페이스를 구현할 수 있습니다.

특징을 장점(좋은 점)과 강점(다른 대상과 비교시에 좋은 점)에서 뽑아쓰자!

객관적인 표현과 주관적인 표현은 분리해서 사용하자

의견을 근거와 함께 쓰자.

개발가이드는 거칠게도,공손하게도 쓰지말자 -> 개발가이드내에서는 여지를 남기면 안된다.

주장을 했으면 이유를 바로 말하자! (강아지 혼내듯이)

문제와 답을 붙여서 쓰자(과정을 길게 이어서 쓰지말자)

메뉴얼에서는 서사식으로 전개하되 단계와 단계의 목적을 정리하자

글쓰기의 계획 단계

  1. 이 글을 왜 쓰는가?
  2. 이 글을 읽는 독자는 누구인가?
  3. 이 글을 읽는 독자에게 무엇을 말하려고 하는가?
  4. 이 글이 주장하는 바가 무엇인가?
  5. 이 글이 주장하는 바의 근거가 분명한가?

개발 글쓰기

  1. 소재 우선 글쓰기 -> 케이스에 중심적으로 글을 쓰자
  2. 자기 수준 글쓰기 -> 더 자세한 설명은 링크를 활용하자
  3. 재미있는 글쓰기 -> 경험을 바탕으로 공감하고 끄덕이게만들자

저.술.편.집

  1. 저 -> 직접 실험하고 경험한 과정이나 결과
  2. 술 -> 어떤 것을 분석하여 의미를 풀이하고 해석한 것
  3. 편 -> 산만하고 복잡한 자료를 편집해 질서를 부여한 것
  4. 집 -> 여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것

(저)

목차를 정하고 본문부터 써보자 -> (2차원 -> 1차원 / 성공한 루트와 실패한 루트를 구별하자)

네이버 기술블로그를 참고하자!

(술)

기술의 자세하게 또는 비유해 설명한 것, 비슷한 용어를 비교해 풀이한 것, 에러 해결 방법

경전을 자기방식으로 풀이하는 개발자!

(편)

프로그램 설치, 개발방법, 튜토리얼 등

시간 순서대로 정리 -> 단계로 서순으로 정리한 내용을 다시 정리

(집)

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

명령어 모음, 팁, 00가지 규칙

네이버와 우아한형제들의 기술블로그