개발자의 글쓰기 / 김수철
개발자의 글쓰기 - 코딩 관련
시작하기 앞서
최근 '개발자의 글쓰기'라는 책을 읽었다. 책 표지에 써있듯이 책의 내용은 변수 네이밍, 릴리즈 노트 작성, 장애 보고서 작성, 기술 블로그 작성 등 개발자의 글쓰기와 관련된 내용이다.
개발을 하면서 막상 변수명이나 함수명을 지을 때 굉장히 많은 고민이 되었었는데, 이 책을 읽고 나니 어느정도 도움이 된 것 같다. 개발을 이제 막 시작하는 사람 혹은 나처럼 개발은 하고 있지만 변수 또는 함수 네이밍에 어려움을 겪고 있는 사람들에게 도움이 될 만한 내용이 있어보여 내용 중 일부를 발췌해 정리해보았다.
또한 개발자라면 기술 블로그 작성에 관심이 많을 것 같은데, 이 책에서는 그 내용 또한 짧게 다루고 있어서 어떻게 시작해야하나? 하는 사람들에게 도움이 될 것 같다. 나 또한 지금 운영 중인 브런치에 어떤 내용, 어떻게 올릴까 구상만 하고 있었는데, 이 책을 읽고 어느정도 가닥이 잡혔다.
이제 막 시작하는 개발자에게 도움이 되었으면 좋겠다.
1. 개발 글쓰기
개발 글쓰기의 예시
이 책에서는 개발자의 글쓰기는 달라야한다고 주장하고 있다. 아래 구조처럼 개발 글쓰기를 예시로 들었는데, 이를 보면 개발자의 글쓰기는 군더더기를 다 없애고 핵심만 남겨 간결하게 써야한다는 것을 알 수 있다.
개발 글쓰기 예시
OOO 서비스 업그레이드 결과
이번 대규모 업그레이드 특징은 3가지 입니다.
1. 완전히 새로운 기능이 추가되었습니다.
2. 버그 없는 안정성을 확보했습니다.
3. 인공지능으로 콜센터를 대체했습니다.
업그레이드 과정은 3단계로...
- 1단계는 ...
개발자 글쓰기의 특징: 정확성, 간결성, 가독성
개발자가 주로 쓰는 글은 주로 클래스나 함수의 이름, 주석, 에러 메시지, 릴리즈 문서, 개발 가이드 등이다. 이러한 글과 문서는 정확하고 간결하며 가독성이 높아야한다.
그러므로 기획서나 전략보고서 등을 쓰는 기획자나 관리자의 글쓰기에 논리력, 설득력, 실행력이 중요하다면 개발자의 글쓰기에는 정확성, 간결성, 가독성이 중요하다.
1) 정확성
틀림이 없이 확실한 것을 말함. → 글로 쓰인 대로만 개발하면 버그 없이 실행되어야 함
2) 간결성
글에 군더더기가 없고, 간단하고 깔끔한 것을 말함. → 구구절절 설명하는 것이 아니라 핵심만 써야함
3) 가독성
쉽게 읽히는 것을 말함 → 쉬운 용어를 사용하고, 필요시 표나 그림으로 잘 정리해야함
문장과 단락을 구조화하는 법
문장을 쉽게 쓰는 방법은 간단한 문장 구조로 핵심만 말하는 것이다. 설명이 필요하다면 핵심 뒤에 부가설명을 하면 된다.
이 부분은 어떤 글쓰기를 하던 지 굉장히 중요한 부분이라 생각된다. 예전에 내 문장이 그렇게 이상한가요? (김정선) 책을 읽고서도 많이 느꼈었고, 번역 도서를 읽으면서도 굉장히 불필요한 말이 문장에 많이 들어가있다는 것을 느꼈었다.
특히 전문적인 IT 지식이 많이 들어가게 되는 개발자의 글쓰기에서는 문장 구조화가 더더욱 잘 되어야한다고 생각한다.
문장 구조화 예시
색상 RGB 값을 각각 사용하기 때문에 입력 데이터는 3차원 벡터다. → 입력 데이터는 3차원 벡터다. 색상 RGB 값을 각각 사용하기 때문이다.
개발자의 글쓰기 (김수철) 본문 중
내가 직접 첨삭한 문장
예시1
Lean Stream을 활용하여 실시간으로 발생하는 빅데이터를 정확하고 신속하게 Lean Stream 전용 UI를 통해 분석할 수 있습니다.
→ 실시간으로 발생하는 빅데이터를 Lean Stream 전용 UI에서 정확하고 신속하게 분석할 수 있습니다.
예시2
글을 쓰는 시점을 기준으로 스파크 코드에 기여한 사람이 1,000명을 넘어섰으며 이것은 다른 프로젝트들이 꿈꾸는 수준을 넘어 훨씬 더 큰 규모입니다.
→ 글을 쓰는 시점을 기준으로 스파크 코드에 기여한 사람이 1,000명을 넘어섰습니다. 이 정도의 기여자 수는 다른 프로젝트들이 목표하는 수준보다 훨씬 더 큰 규모입니다.
2. 변수 및 함수 네이밍 관련
변수명 네이밍
영어 단어 선택과 외래어 표기법
1) 반대말
각 영어단어의 반대말을 정확히 써야한다.
Show ↔ Hide
Invisible ↔ Visible
Header ↔ Footer (tail, toe, foot)
Before ↔ After
Open ↔ Close
Input ↔ Output
Import ↔ Export
2) 미만/초과/이하/이상
미만 : under
초과 : over
이하 : or under
이상 : and over
3) 비슷한 말
서로 의미는 비슷하지만 개발에서 사용하는 의도가 다른 단어들을 주의해서 사용해야한다.
중단
Stop : 잠시 중단하는 것, 언제든 재시작 가능
End : 완전히 중단되어 재시작할 가능성이 없는 경우
Finish : 이미 끝장을 본 상태, 재시작 고려할 필요 없음
Pause : 아주 잠시 일시적으로 중단된 것이어서 금방이라도 다시 시작할 것 같은 상황
Suspend : 다음 단계의 시작을 중단한 것
Hold : 어떤 의도가 있어서 중단한 것
예시
stopUserRegister();
// 사용자 등록을 잠시 중단한다. 재개하려면 startUserRegister()나 restartUserRegister()를 사용한다.
endUserRegister();
// 사용자 등록을 종료한다. 사용자가 등록을 새롭게 시작하려면 beginUserRegister()를 사용한다.
finishUserRegister();
// 사용자 등록을 완전히 종료한다. 이 함수를 실행한 후에 다시 사용자 등록을 요청하면 에러가 발생해야 한다.
가져오다
Get : 어떤 값을 돌려받아서 반환하는 함수에서 사용
Retrieve : 검색(search)해서 가져온다(get)는 뜻 → 검색에 무게가 실린다면 retrieve를 쓰는 편이 낫다
Fetch : 현재 값을 가리키는 포인터가 다음 값으로 이동 (moveNext) 한 것을 가져온다(get)는 뜻
Return : 함수 이름에 쓰지 않음 → 함수 안에서 제어에 쓰기 때문
Acquire : 독점한다는 뜻 → 다른 함수가 가져가지 못하게 독점하고자 할 때 쓰면 됨
설정
Set : 값을 변경하거나 설정하는 함수에 씀
Init : 초기화 설정인 경우 씀
생성
Create : 정해진 틀이 없으므로 먼저 틀을 만들때 씀
Register : 이미 정해진 틀에 값을 집어넣는 것
변경
Change : 내용을 단순히 바꾸는 것
Modify : 잘못된 것을 바로잡을 때 사용
Revise : 기존에 없던 새로운 정보나 아이디어를 덧붙여 기존 내용과 달라졌음을 분명히 할 때 사용
변수
Parameter : 매개변수, 함수에 정의한 변수 (variable)를 뜻함
Argument : 전달 인자, 함수를 호출할 때 전달되는 값 (value)을 뜻함
속성
Attribute : html에서 태그 안에 속성을 넣을 때 사용되는 요소
Property : attribute와 동일하나 HTML DOM에서 가르킬 때 사용
함수명 표기법
1) 접두사
doSomething() : 행동이 필요한 함수
isSomthing() / doesSomething() : bool 값을 반환하는 함수
좋은 이름이 가진 5가지 특성
SMART
Easy to Search 검색하기 쉽고
Easy to Mix 조합하기 쉽고
Easy to Agree 수긍하기 쉽고
Easy to Remember 기억하기 쉽고
Easy to Type 입력하기 쉽고
3. 주석
주석을 써야하는 이유 혹은 목적
코드에서 표현하지 못한 어떤 의도를 전달하기 위해 사용
의도를 전달하는 이유는 다른 개발자들을 위한 것임
왜 이렇게 작성했는지 설명하고 뜻밖의 발견을 제시하거나 새로운 아이디어를 보여주거나 어떤 방법이 더 좋은지 알려주는 것은 모두 다른 개발자들을 배려하는 마음임
주석이란
이유를 알려주는 것
개발자가 새롭게 발견한 것
예상 질문과 답
할 일이나 주의, 개선 아이디어를 주는 것 (todo, hack..)
다른 사람에게 보완을 요청하는 것
개발자의 속마음을 표현하는 것
4. 개발자의 글쓰기
개발자가 기술 블로그를 잘 못 쓰는 이유
블로그에 글을 쓰는 방법이 학생이었을 때 배운 글쓰기 방법과 다르기 때문
학교에서 배운 글쓰기는 글의 목적, 독자, 독자에게 전달하려고 하는 것, 주장하는 것, 근거의 명확성을 중시하는 주제 우선 글쓰기, 독자 중심 글쓰기, 주장하는 글쓰기 방법임
그러나 개발자의 글쓰기는 어떤 주장이 있는 것이 아닌 그냥 내가 해봤더니 이랬더라 라는 갭라 과정 자체를 말하려는 것임
또한 기술 블로그를 읽는 독자의 수준도 일정하지 않기 때문에 폭과 수준이 다양한 독자를 대상으로 '초등학생도 이해할 수 있는 수준'으로 글을 쓸 수 있는 개발자는 없음
개발자에게 적합한 글쓰기 방법 세 가지
첫째, 소재 우선 글쓰기
소재의식은 특정한 대상이나 상황에 대한 자기만의 관점이나 생각, 해결 방안을 뜻한다.
어떤 문제로 인해 발생한 상황인지를 설명하고, 그 상황을 어떻게 해결했는 지로 구성되는 것이 소재 우선 글쓰기이다. 일상을 다룬 수필이나 에피소드와 비슷하다.
예시
둘째, 자기 수준 글쓰기
기술의 수준은 사람마다 천차 만별이기 때문에 독자 수준에 맞춰 글을 쓰는 것이 매우 어렵다. 그러므로 기술 블로그를 쓸 때는 독자 수준이 아니라 작성자 수준으로 쓰는 편이 낫다. 만약 어려운 용어나 사람들이 잘 모를 것 같은 용어 등이 있다면 이는 부연설명을 할 것이 아니라 해당 내용에 대해서 잘 정리된 링크를 걸어두면 된다.
독자에게 모든 것을 다 설명하는 것이 아니라 핵심 내용만 쓰자!
셋째, 재미있는 글쓰기
개발자의 경험에서 우러나오는 내용을 적절한 글쓰기 기교로 녹아내자.
사내 위키에 올린 것들 중 공유할 수 있는 것들을 브런치에 올리면 좋을 텐데, 그렇지 못해서 많이 아쉽다. 어느 한 곳에 올리면 다시 포맷팅하는 것도 은근 시간이 많이 들기도 하고.. 그래도 틈틈히 메모장에 적어두었던 개발 관련 팁들을 올릴 수 있도록 노력해봐야겠다!
글을 읽는 모든 분들의 라이킷과 댓글을 환영합니다. ;-)
Copyright 2020. April all rights reserved.
