- 저자
- 김철수
- 출판
- 위키북스
- 출판일
- 2019.10.04
개발자의 글쓰기, 저자 김철수, 출판 위키북스, 2019
기획자나 관리자의 글쓰기에 논리력, 설득력, 실행력이 중요하다면, 개발자의 글쓰기에는 정확성, 간결성, 가독성이 중요하다
- 20p
[입력 데이터]
입력 데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.
문장을 쉽게 쓰려면 이처럼 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다. 이때 문장의 주어를 가져다가 소제목으로 만들면 자연스럽게 문단을 구성할 수 있다.
- 27p
문어세어 계층은 굵기, 모양, 밑줄, 줄 간 거리 등으로 표현된다.
- 33p
어쩌면 개발자가 가장 힘들어하는 일이 이름 짓기일지도 모른다. 실제로 2013년에 Quora 사이트와 Ununtu 포럼에서 개발자 4,522명에게 설문했더니 그들의 절반이 이름 짓기가 가장 힘들다고 대답했다.
- 47p
i는 변수 이름이지만 d는 아니다
- 56p
배열을 복수로 나타내는 방법이 있다. userName을 userNames라고 쓰는 것이다. 변수명에 복수형을 나타내는 -s 가 붙어 있기 때문에 쉽게 알아볼 수 있다.
- 58p
함수명 중간에 사용할 때는 -s가 눈에 잘 띄지 않는다.
checkUserNamesUnder2Characters()
그래서 변수명은 그냥 두더라도 함수명에는 -s 대신 다음과 같이 'array'나 'list of'를 쓰는 편이 더 나을 수도 있다.
checkUserNameArrayUnder2Characters()
- 59p
중요한 단어를 앞에 쓴다
변수 이름을 여러 단어로 조합할 때는 순서를 잘 정해야 한다. 예를 들어 총 방문자 수를 나타내는 변수를 보통 totalVisitor로 그대로 번역해 변수로 사용하곤 한다. 하지만 이 변수를 다시 사용할 때는 total로 검색을 시작하는 경우보다 visitor로 검색을 시작하는 경우가 더 많을 것이다. 따라서 total이라는 수식어보다는 본래 의미를 뜻하는 visitor를 앞에 쓸 것을 추천한다
int totalVisitor -> int visitorTotal
- 60p
좋은 이름이 가진 5가지 특징
- easy to Search 검색하기 쉽고
- easy to Mix 조합하기 쉽고
- easy to Agree 수긍하기 쉽고
- easy to Remember 기억하기 쉽고
- easy to Type 입력하기 쉽고
- 65p
SERVER_TIMEOUT -> ERROR_SERVER_TIMEOUT
big_strong_text -> title
- 68 ~ 70p
처음부터 주석 없이 코딩하는 연습을 하자
- 77p
코드는 의미를, 주석은 의도를
- 83p
개발자용 에러 메시지와 사용자용 에러 메시지를 분리하자
- 99p
사용자 에러 메시지에는 에러의 내용, 에러의 원인, 에러 해결방법이 포함되어야 한다.
- 102p
엘리베이터 스피치라는 말이 있다. 투자자를 엘리베이터에서 만났을 때 그 짧은 시간에 사업 계획의 핵심만 종합해 말하는 방식을 말한다. 이 경우 다음과 같은 투자자의 질문에 대답할 수 있어야 한다.
" 그래서, 한마디로 뭘 한다는 거죠?'
" 그래서, 핵심이 뭔가요?"
체인지 로그도 마찬가지다. 상사나 고객이 체인지 로그를 하나씩 뜯어보기 전에 이번 릴리스가 이전과 비교해서 뭐가 다르고 핵심과 컨셉이 무엇인지 한마디로 알려줘야 한다. 그러려면 릴리스 내용 전체를 종합해서 한 문장으로 만들고 그것을 체인지 로그 첫 줄에 적어야 한다.
- 127p
예를 들어 다음과 같이 세 가지 방식으로 버전을 올렸다고 하자.
1. 버전 1.2.2 -> 1.2.3
2. 버전 1.2.2 -> 1.3.0
3. 버전 1.2.2 -> 2.0.0
1번은 세 번째 자리에서 버전을 올렸다. 이것은 간단한 패치를 의미한다. 그래서 이전 버전과 호환된다.
2번은 두 번째 자리에서 버전을 올렸다. 두 번째 자리에서 버전을 올리면 그 다음 세 번째 자리는 0으로 초기화된다. 이것은 새로운 기능을 추가했을 때다. 1.3.0은 1.2.x와 일부 호환될 수 있으나 새로운 기능을 1.2.x에서 사용할 수는 없다.
3번은 첫 번째 자리에서 버전을 올렸다. 이 경우는 전면적인 업그레이드여서 이전 버전과는 거의 호환되지 않는다고 볼 수 있다. 프로그램의 명맥은 잇겠지만 완전히 다른 프로그램이다.
- 137p
깃허브의 공동창업자인 톰 프레스턴 베르너가 정한 Semantic Versioning을 제시한다. ...
- 버전은 X.Y.Z 형태로 한다. X, Y, Z는 자연수로서 각각 독립적으로 증한다. X, Y, Z를 구분하는 점은 소수점이 아니라 구분 기호다. 따라서 1.1.12는 1.1.9보다 높은 버전이다. X를 Major, Y를 Minor, Z를 Patch로 간편하게 이해해도 좋다.
- X가 0인 것은 초기 내부 개발에서만 사용하고 최초 공개 API는 1.0.0이어야 한다. X는 기존 버전과 호환되지 않는 변화가 있을 때만 1씩 올린다.
- Y는 기존 버전과 호환되는 새로운 기능이 추가됐을 때 1씩 올린다. 큰 규모의 패치가 있을 때 작은 규모의 패치와 구분하기 위해 Y를 올릴 수도 있다. 만약 X를 올리면 Y는 초기화되어야 한다. ...
- Z는 기존 버전과 완전히 호환되면서 작은 규모의 패치가 있을 때 1씩 올린다. X나 Y를 올리면 Z는 0으로 초기화돼야 한다.
- 138p
문제와 문제점을 구별하자
- 문제 : 사용자가 급증하면 서버가 정지
- 문제점 : 잘못된 시스템 설정, 프로그램 비 최적화, 잘못된 DB 설계
- 140 ~ 141p
보카시 장난으로 말을 하면 의사결정을 할 수 없다. 그래서 개발자는 좀 더 정치적으로 확정해서 말할 필요가 있다. 재발할지도 모른다면 그냥 재발 가능성을 20%라고 말하면 된다.
- 161p
의견을 쓰려면 근거를 대자
- 184p
'한 번만 받으면 됩니다'를 개발자의 의도 없이 명확하게 쓰려면 '한 번 받습니다'나 '한 번만 받습니다'로 고치면 된다.
- 187p
개발문서에서 서사는 결국 개발자와 독자 사이의 줄다리기 같은 것이다. 개발자는 의미 없는 것은 빼고 중요한 것은 넣기를 원한다. 독자도 의미 있는 것만 남고 무엇이 중요한지 구별해 주기를 원한다.
... 좋은 방법은 기술의 범용성을 기준으로 하는 것이다.
- 198 ~ 199p
첫째, 주제 의식을 버리고 소재 의식으로 쓰자
주제 의식이 민족이나 권선징악, 자존감이나 자본주의 같은 추상적 가치를 기반으로 한다면 소재 의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 해결 방안을 뜻한다.
- 233p
둘째, 독자 수준이 아니라 자기 수준으로 쓰자
- 235p
셋째, 재미있게 글을 쓰자.
-239p
우아한형제들 기술 블로그는 주말 밤에 야근 하는 개발자들끼리 대화하듯이 자연스러운 표현과 실감 나는 구성, 자극적인 제목과 제약 없는 묘사가 두드러진다. 그래서 약간은 비전무적이면서 글을 대충 쓴다는 느낌도 든다.
... 목차와 내용을 보면 네이버나 카카오 기술 블로그 스타일과 완전히 다르다는 것을 알 수 있다. 이것은 확실히 기업 문화의 차이에서 기인한다. 네이버와 우아한형제들의 기업 문화의 차이가 기술 블로그의 문체나 구성에도 그대로 적용되는 것이다.
- 267p
'Book' 카테고리의 다른 글
| [독서 기록] 모던 자바 인 액션 1장 자바 8, 9, 10, 11 : 무슨 일이 일어나고 있는가? (0) | 2023.01.04 |
|---|---|
| [독서 기록] 객체지향의 사실과 오해 (1) | 2022.12.08 |
| [독서 기록] 나는 주니어 개발자다 (0) | 2022.11.22 |
| [독서 기록] 자바로 배우는 리팩토링 입문 (0) | 2022.11.22 |
| [독서 기록] 엘레강트 오브젝트 - 새로운 관점에서 바라본 객체 지향 3장 - 2 (2) | 2022.11.19 |
