개발자의 글쓰기

개발자는 정확성, 간결성, 가독성 있게 글을 잘 써야 한다.
그리고 자신의 코드 그리고 개발 관련 사항에 대해서 설명을 해야할 일들이 매우 많다.

개인적으로 업무를 하면서 제일 머리 아픈 작업은
내가 짠 코드나 개발 관련 사항을 누군가에게 설명하는 거 그리고 네이밍이다.

그래서 일기도 안 쓰는 나에게 글쓰기라는 단어 자체가 어색하긴 하지만,
꼭 필요한 글쓰기 능력을 키우기 위해 개발자의 글쓰기라는 책을 스터디 하게 되었다.

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

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

• 문장을 구조화하는 법

문장을 쉽게 쓰려면 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다.
이때 첫 문장의 주어를 가져다가 소제목으로 만들면 자연스럽게 문단을 구성할 수 있다.

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

개발자의 생각을 글로 표현하는데는 크게 세가지 방법이 있다.

1. 서술식 : 줄거리가 있는 설명이나 이야기
2. 개조식 : 여러 가지 종류의 항목과 내용이 반복되거나 서술식에서 강조가 필요한 내용
3. 도식 : 각 항목이나 사항의 관계를 명확히 규정하고 싶은 경우

• 단락을 구조화하는 위계

비즈니스 문서에서 위치와 계층은 항상 붙어 다닌다.
위치만 있어서도 안되고 계층만 있어서도 안 된다.
글을 쓸 때는 항상 위계가 잘 드러나게 글을 쓰고 표현해야 한다.

02. 쉽게 쓰는 띄어쓰기와 문장 부호

• 가장 쉬운 띄어쓰기 원칙

1. 조사,순서,숫자,하다, 기호만 붙이고 나머지는 띄어 쓴다.
2. 코딩에서는 조사와 비슷한 것이 쉼표다. 쉼표는 앞 낱말에 붙여야 한다.

var obj = {
	arg1: 1,
	arg2: 2,
	arg3: 3
};

** 근데 개발하다보면 앞 낱말이 너무 긴 경우 뒷 낱말 앞에 쉼표를 붙이는 경우도 있는데??
3. 일, 이, 삼과 같은 한글 숫자가 순서나 단계를 나타낼 떄는 뒤 낱말과 붙인다.
4. 기호는 모두 앞 낱말과 붙인다.
5. 함수를 선언할 때 함수 이름 끝에 괄호를 쓰고 그 안에 인수를 쓰는데, 이때도 붙여 쓴다.

wordSpacing(arg1,arg2)

** 이건 잘 지키고 있음!

03. 영어 단어 선택과 외래어 표기법

• 비슷한 듯 다른 듯, 단어 선택

정확한 단어를 쓰는 것도 중요하지만 그보다 더 중요한 것은 얼마나 일관성있고 개연성 있게 쓰느냐다.
프로그램 안에서 일관성과 개연성만 있다면, 또는 그 프로그램의 코드를 보는 개발자 사이에 일관적이고 개연적인 합의만 돼 있다면 어떻게 쓰든 상관없다.

** 보통 실무에서 데이터 조회해서 값을 가져올 때, get 이라는 동사를 앞에 붙여서 메소드를 작명하는데 개인적으로는 find 가 더 적절하다고 생각하지만
이미 구현되어 있는 로직들과 일관성을 맞추기 위해 get 을 사용하고 있다.

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

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

• 개발자의 가장 큰 고민은 이름 짓기 (인정!!!!!!)

이름 짓기가 어렵긴 하지만 잘만 하면 코드를 짜기도 쉽고 이해하기도 쉽다.
다른 개발자와 소통하기도 쉬워지고, 공개할 경우 외부 개발자에게 인정도 받는다.
문서 대신에 코드로 소통하려면 좋은 이름 짓기는 필수다.

다른 개발자가 봤을 때 한번에 무슨 뜻인지, 무슨 기능을 하는지 알아낼 수 있는 이름이어야 한다.
그러면서도 아주 간결해야 한다.

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

이름 짓기는 창조 과정이 아니라 정해진 원칙으로 적절한 단어를 선택해 조합하는 과정일 뿐이다.

** 인정..네이밍할 때 이미 관련 내용과 비슷하게 작명된 건이 있는지 구현된 로직을 찾는다.
디비 단어 용어 사전 외에 코딩 시에 참고할만한 단어 용어 사전도 있으면 좋을 것 같다.

몇 가지 중요한 네이밍 규칙을 데이터로 증명했다.

1. 자바 네이밍 컨벤션을 철저히 준수한다.

-- 클래스는 UpperCamelClass(UserService.class)
-- 함수와 변수는 lowerCamelClass(string userName = "하영";)
-- 상수는 UPPER_DELMITER_CASE (final int MAX_AGE = 9;)

2. 네이밍은 보통 16글자, 3단어를 조합한다.

3. 품사는 주로 명사, 동사, 형용사의 조합이다.

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

패키지와 모듈 이름은 모두 소문자로 쓰는 것으로 누군가 정했고, 그것이 그대로 컨벤션으로 자리 잡았다.

02. 변수 이름을 잘 짓는 법

• i는 변수 이름이지만 d는 아니다.

i는 정수를 뜻하는 integer 와 지수를 뜻하는 index의 첫 글자로 간주되므로, 개발자가 반복문의 카운더나 배열 인덱스로 i를 사용해도 이상할 것이 천혀 없다.
하지만 d 와 같이 아무런 의미가 없는 글자를 변수로 쓰는 것은 좋지 않다.

• 긴 이름? 짧은 이름? 검색 잘되는 이름!

• 복수형을 나타내는 s를 붙일까 말까?

** s 를 붙일까 말까 고민을 실무에서 많이 하는데, 개인적으로는 LIST 로 정의하면 -List 를 붙이고 Set 으로 정의하면 -s 를 붙인다.
팀 내 컨벤션으로 정리를 하면 좋을 것 같다.

• 약어를 쓰는 것이 좋을까? 안 쓰는 것이 좋을까?

** 현재 응답으로 내려주는 필드나 너무 긴 경우 약어를 쓰긴하지만 대부분 가독성을 위해 풀어쓰고 있다.

• 중요한 단어를 앞에 쓴다.

** totalVisitor 보다 visitorTotal 이 좋은 예라고 책에서 말하는데, 나는 totalVisitor 이 더 좋은 예라는 생각을 한다.
방문자가 아닌 방문자 전체인 점이 중요한거 아닌가??

• 함수 이름 짓는 순서

일단 핵심 단어들을 나열하고 중요한 순서대로 배열하고 핵심 단어 외에는 제거하는 방식으로 진행한다.

03. 좋은 이름의 기준, SMART

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

1. easy to Search : 검색하기 쉽고
2. easy to Mix : 조합하기 쉽고
3. easy to Agree : 수긍하기 쉽고
4. easy to Remember : 기억하기 쉽고
5. easy to Type : 입력하기 쉽고

** 좋은 이름 짓기 어렵구만..ㅋ

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

• 이름을 잘 지으면 주석을 줄일 수 있다.

사실 이름을 잘 지으면 주석을 대폭 줄일 수 있다.
이름이 주석이 할 일을 대신하기 때문이다.

• 처음부터 주석 없이 코딩하는 연습을 하자.

** 개인적으로 메소드 명을 작명할 때, 메소드 내에서 처리하는 작업이 많은 경우 이름 작명이 어려워 주석으로 메소드의 작업을 설명한 적이 많은 거 같다.
주석을 쓰기 전에 좀 더 메소드 명을 신경써야겠다..

• 주석이 필요한 때도 많다.

** 기획 내용이 중간에 변경되거나, 히스토리 관리성으로 주석을 추가하는 경우가 있다.

05. 다른 개발자를 배려하는 주석 쓰기

• 코드는 의미를, 주석은 의도를

코드에 표현하지 못한 어떤 의도를 전달해야 할 때는 주석을 쓸 수밖에 없다.

1. 이유를 알려주는 것
2. 개발자가 새롭게 발견한 것
3. 예상 질문과 답
4. 할 일이나 주의, 개선 아이디어를 주는것
   ** 할 일에 대해 FIXME / TODO 를 사용하는데 주석 컨벤션도 팀 내 컨벤션으로 정리해놓으면 좋을 것 같다.

• 주석의 반복
  ** copy&paste 를 많이해서 주석의 반복 케이스가 많은듯..반성..

• 주석도 코드다
  ** 인정.. 제대로 관리안되는 주석은 없는게 나음.