개발자의 글쓰기 - 김철수

 

책을 읽으면서 중요한 포인트 및 느낀점들을 쓰고 있습니다.

 

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

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

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

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

 

-> 서술식, 개보식, 도식의 차이

서술식 : '~다'로 끝나는 완전한 문장으로 구성된 글, 무엇을 설명하거나 논증할 때 주로 사용하는 방식
소설이나 신문 기사처럼 개발 가이드 문서는 대부분 서술식으로 쓴다.

개조식 : 명사나 '~했음'로 끝내는 것, 릴리스 문서나 장애 보고서를 쓸 때 개조식으로 쓴다.

도식 : 주로 표를 의미한다. 행렬에 글만 있으면 '표', 그림이 있으면 '도표'라 한다.

-> 단락을 구조화하는 위계

문서에서는 다음과 같이 급이 낮은 문장을 들여쓰기 함으로써 위치를 맞춘다.

ex)
ㅁ 이번 대규모 업그래이드 특징은 3가지 입니다.
	ㅇ 완전히 새로운 기능이 추가되었습니다.
	ㅇ 버그 없는 안정성을 확보 했습니다.

-> 가장 쉬운 띄어쓰기 원칙

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

[조사] ~가 ~이 등
var obj = {
	arg1: 1,
	arg2: 2,
	arg3: 3
};

[숫자, 하다] 일, 3, ~하다
wordSpacing(arg1, arg2)

[문자, 문자열] '', ""
char str[] = "HELLO";
str[0] = 'A';

 

-> 영어 단어 선택과 외래어 표기법

stop(), start(), restart()
end(), begin()
finish()

 

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

자바 네이밍 컨벤션을 철저히 준수한다.
	클래스는 UpperCamelCase
	함수와 변수는 lowerCamelCase
	상수는 UPPER_DELIMITER_CASE

 

-> 가독성과 소통이 먼저다

코드를 읽기 쉽게 만들고 다른 개발자와 소통하기 위해서 만들어진 표기법이다.
소통이 잘 되려면 서로가 같은 컨벤션을 지켜야 한다.
코딩하기 전에 기본적인 컨벤션 규칙을 정하는 것이 우선이다.

 

-> 중요한 단어를 앞에 쓴다.

ex)
before :
	int totalVisitor
	int totalRegister
    
after :
	int visitorTotal
	int registerTotal

 

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

검색 (Search)
조합 (Mix)
수긍 (Agree)
기억 (Remember)
입력 (Type)

위의 5가지가 쉽도록!

 

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

코드에 표현하지 못한 어떤 ㅡ이도를 전달해야 할 떄는 주석을 쓰자

letsEatSomething() // 내가 배가 고픈 상황

or

letsEatSomethin() // 내가 심심한 상황

 

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

1. 에러 내용 : 회원가입을 진행할 수 없습니다.
2. 에러 원인 : 휴대전화 번호를 잘못 입력하셨습니다.
3. 에러 해결 방법 : 휴대전화 번호 입력란에는 숫자만 입력하십시오

 

-> 체인지 로그는 적절한 양으로 써야한다.

1순위 : 개발자가 노력을 많이하고, 독자가 관심 있는것 
삭제 : 개발자가 노력을 덜 했고, 독자가 관심 없는것

 

https://coupa.ng/bT6o2C

위키북스 개발자의 글쓰기 + 미니수첩 증정

“파트너스 활동을 통해 일정액의 수수료를 제공받을 수 있음"