개발자의 글쓰기 - 김철수

이 책을 읽고 기억하고 싶은 부분을 기록했습니다. ✏️

전부 책에서 가져온 내용이고

제가 아주 조금 재구성 했습니다.

책을 직접 읽어보시는 것을 추천드립니다. 

 

 

 

 

[1] 변수이름 잘 짓는 법

1.1 날짜를 표현할 때 

 

일자 day를 뜻하는 변수를 설정하고 싶다면 그냥 day를 사용하면 된다.

그런데 그냥 day는 없다. 프로그램은 항상 어떤 의미와 의도를 가진 day만을 사용한다.

 

[ 안좋은 예 ]

int d
int m
int y

 

[ 좋은 예 ]

int someday
int today
int thismonth
int finalYear

int daysSinceCreated
int monthSinceUpdated
int yearsSinceRegistered

 

1.2 중요한 단어를 앞에 쓰기

 

변수 이름을 여러 단어로 조합할때는 순서를 잘 정해야한다.

예를들어 방문자 수를 나타내는 변수를 보통 totalVisitor로 그대로 번역해 변수로 사용하곤 한다.

하지만 이 변수를 다시 사용할때는 total로 검색을 시작하는 경우보다

visitor로 검색을 시작하는 경우가 더 많을 것이다. 

따라서 total이라는 수식어보다는 본래 의미를 뜻하는 visitor를 앞에 쓸 것을 추천한다. 

 

[ 안좋은 예 ]

int totalVisitor
int totalRegister
int totalBuyer
int totalSalesOfThisMonth
int maxSizeOfWindow
int numberOfTotalVIP

 

[ 좋은 예 ]

int visitorTotal
int registerTotal
int buyerTotal
int salesOfthisMonthTotal
int windowSizeMax
int vipCount

 

1.3 응답 키값

 

구독자 추가를 했을때 내려주는 json 응답 키값을 살펴봅시다. 

 

[ 안좋은 예 ]

"success": [  // 구독자 추가 성공

],
"update": [ // 이미 있는 구독자, 나머지 필드를 업데이트 함

], 
"failDeny": [ // 수신 거부 상태의 구독자, 추가하지 않음

],
"failWrongEmail": [ // 잘못된 이메일 주소 형식, 추가하지 않음

],
"failUnknown": [ // 알수없는 오류로 추가하지 않음

]

 

첫번째 키를 success라 이름 짓고 주석으로 '구독자 추가 성공' 이라고 썼다.

그럼 뒤에 나오는 update는 실패인가? 분명 아닐 것이다.

여기서는 구독자가 없으면 새로 등록하고 구독자가 있으면 구독자 정보를 갱신하는 것이므로,

success와 update 가 아니라 create와 update로 표현하는 것이 옳다.

 

update의 경우에도 이메일을 제외한 나머지 필드를 업데이트한다고 했으니

키 이름을 updatedInformationExceptEmail로 쓰면 주석이 필요하지 않다.

 

나머지 세가지는 모두 구독자로 추가되지 않는 경우다. 

하지만 키 이름에 fail을 써서 fail을 설명하기 위해 주석에 '추가 하지 않음'을 일일이 다 쓴 것이다.

 

이 경우에는 키 이름에 noCreated를 붙이기만 하면 된다.

 

[ 좋은 예 ] 

"created": [

],
"updatedInformationExceptEmail": [

],
"noCreatedBecauseUnsubscriber": [

],
"noCreatedBecauseWrongEmail": [

],
"noCreatedBecauseUnknownError": [

]

 

 

1.4 이하 또는 미만을 정확히 표현하기 

 

3글자 이하는 

 

- 3 and under

- 3 or less

- 3 or below 

 

라고 쓴다.

 

3글자 미만는 

 

- under 3

- less than 3

- below 3

 

라고 쓴다. 

 

 

예를 들어 checkUserNameUnder3Characters() 라는 메소드가 있을때 

영어를 잘못하는 개발자는 그냥 3글자 이하 라고 생각할 수 있지만

영어를 잘하는 개발자는 당연히 3글자 미만이라고 생각할 것 이다. 

 

1.5 의미를 나타내는 변수나 메소드 두기

 

[ 안좋은 예 ]

if(user.getLoginCount() > 10 && user.getOwnArticleCount() >= 5) {

    int level = user.getlevel();
    user.setLevel(level++);
}

 

 

[ 좋은 예 ]

if(user.enoughToLevelUp()) {

   user.levelUp();
}

 

 

[2] 에러 메세지 

2.1 에러 메세지 구성

 

에러메세지에는 에러의 내용, 에러의 원인, 에러 해결방법이 포함되어야한다.

 

[ 안좋은 예 ] 

 

 

[ 좋은 예 ]

 

 

- 에러 내용: 회원가입을 진행할 수 없습니다.

- 에러 원인: 휴대전화 번호를 잘못 입력하셨습니다.

- 에러 해결 방법: 휴대전화 번호 입력란에는 숫자만 입력하십시오.

 

가 다들어갔다. 

 

 

2.2 오락 가락 메세지는 노우!! 

 

게시물을 작성하다가 취소버튼을 눌렀을때 

사용자를 배려해서 재확인 메세지를 알림창으로 보여주기도 한다. 

 

[ 안좋은 예 ]

 

 

'예' 버튼을 누르면 어떤 결과가 벌어질까?

편집한 내용이 취소돼서 다른 페이지로 이동할까?

아니면 편집한 내용이 취소 될 수 이으니 이 페이지를 떠나는 행위 자체를 취소할까?

 

'아니오' 버튼도 마친가지다.

이 페이지를 안떠나겠다는 것일까?

아니면 편집한 내용을 안쓰겠다는 것일까?

 

이렇게 상황이 애매해진 이유는 '취소' 라는 단어를 두번 써서 그렇다.

취소를 아예 쓰지 말고 행동에만 집중하면 오해를 없앨 수 있다. 

 

[ 좋은 예 ]

 

 

페이스북 처럼 짧고 애매한 것보다는 길더라도 분명하게 표시하는 방법도 좋다. 

 

 

 

[3] 버전

 

 

 

 

[4] 서비스 

 

서비스 매뉴얼을 쓸 때는 범주, 용도, 특징으로 설명하자. 

 

 

 

서비스의 범주를 신중하게 결정해야한다. 범주는 서비스의 정체성을 나타낼 뿐만 아니라 검색어와도 연관이 있다.

 

 

 

 

 

[ 추가 ]

 

변수명 지어주는 사이트 발견...!! 근데 넘 느리더라구요ㅠㅠ

 

www.curioustore.com/#!/

Curioustore