[리뷰][IT] 개발자의 글쓰기 - 변수 네이밍부터 기술 블로그까지 글쓰기 고민 끝!!

저는 개발자는 아닙니다만, 티스토리에 IT 관련 공부한 내용을 올리다 보니, 기술적인 내용을 포함하고 있습니다. 
그런데, 기술적인 내용을 너무 소설 쓰는 것 마냥 줄줄이 쓰는 것 같다는 생각을 하고 있었는데요.
지난주에 도서관 신간 목록 보다가 제목이 눈에 띄어서 훑어보니, "기술 블로그 쉽게 쓰고 운영하기"라는 부분이 있었습니다. 제 티스토리가 기술 블로그..라고 하긴 그렇지만, 참고할 만한 내용일 것 같아서 책을 대출했습니다.

읽어보니, 기술 블로그뿐 아니라, 기본적인 글쓰기 요령, 개발자들이 제일 어려워하는 이름 짓기와 주석 쓰기, 에러 메시지, 릴리즈 문서와 장애 보고서 쓰기, 개발 가이드, SI제안서 쓰기 등 전반적으로 개발자가 써야 하는 글과 글 쓰는 요령에 대해 정리되어있습니다. 

아래 내용은 책을 읽으면서 기억해 두면 좋을 것 같은 것들을 정리해 두었습니다.

글 쓰기 기본

작은따옴표, 큰 따옴표

SQL문에서는 작은따옴표를 쓰고, Java에서는 문자열은 큰 따옴표를 씁니다. 저는 이게 자주 헷갈리는데요.
SQL 쿼리문에서 모두 작은따옴표를 쓰는 이유는 쿼리문을 다른 언어에서 큰 따옴표로 인용하는 경우에 큰 따옴표 중복을 막기 위해서라고 합니다. 비슷하게 자바스크립트도 주로 작은따옴표를 사용하고, 그 이유는 HTML이 주로 큰 따옴표를 사용하기 때문에 충돌을 막기 위해서입니다. 기억에 두면 덜 헷갈릴 것 같네요.
비즈니스 문서에서는 작은따옴표와 큰 따옴표를 아래와 같이 사용합니다.

- 책의 제목이나 산문 이름은 큰 따옴표
- 제목 상호 법률 규정 등은 작은따옴표
- 강조를 할 때는 작은따옴표

영어 단어 선택

반대말이나 비슷한 말은 정확하게 사용해야 합니다.
잘 모르거나, 헷갈렸던 것 중에는 다음과 같은 것들이 있었습니다.

- stop: 잠시 중단하는 것이어서 언제든 재시작 가능
- end: 완전히 중단되어서 재시작할 가능성이 전혀 없으나, 새로운 시작은 가능
- finish: 완전히 종료되어서 다시 시작할 가능성이 없는 경우(end와의 차이)
- pause: 아주 잠시 일시적 중단하는 것으로 금방이라도 다시 시작 가능한 상황
- suspend: 다음 단계의 시작을 중단
- hold: 어떤 의도에 의한 중단

- create: 정해진 틀이 없을 때 틀을 만들 때
- register: 정해진 틀에 값을 집어넣을 때

- change: 단순히 내용 변경
- modify: 잘못된 것을 바로 잡을 때
- revise: 기존에 없던 새로운 정보나 아이디어를 덧붙여 기존 내용과 달라졌을 때

- parameter: 매개변수 (함수에 정의한 '변수')
- argument: 전달 인자 (함수를 호출할 때 전달되는 '값')

 

네이밍과 주석 쓰기

네이밍 컨벤션

- 클래스 이름은 파스칼 표기법 (ex. ClassName)
- 변수 이름은 카멜 표기법 (ex. variableName)
- 상수는 모두 대문자로 쓰고 언더스코어(_)로 연결한다. (ex. MIN_MAX_CONSTANT)
- 패키지와 모듈 이름은 모두 소문자로 쓴다. (ex. module.package)
- CSS에서는 BEM표기법은 '대상__요소--상태'를 의미한다. (ex. from__button--disable)

네이밍 컨벤션의 중요한 목적은 가독성과 소통입니다. 하지만, 가독성이 아무리 좋아도 그것을 다른 개발자가 이해하지 못하면 소용없습니다. 어떤 네이밍 컨벤션 규칙을 정하든 관련자들끼리 같은 규칙을 정하는 것이 우선입니다.

변수 이름을 잘 짓는 법

- 가장 많이 쓰이는 변수 i는 Integer, Index의 첫 글자로서 반복문의 카운터나 배열 인덱스로 사용하는 것이 문제가 없고, i에 이어지는 j, k도 마찬가지임
- 현재는 통합개발환경하에서 개발이 되므로 변수의 이름이 길어져도 오탈자 확률이 높지 않으므로 직관적인 이름을 가지도록 작성하는 것이 가능
- 통합개발환경의 발달로 인해 변수명 앞에 변수를 의미하는 m이나 UI 구성요소인 button의 약자로 btn이나 image의 약자로 img를 붙이는 헝가리안 표기법도 이제 더 이상 사용하지 않는다.
- 복수형이 함수 명의 중간에 나올 때는 -s 대신 'array'나 'list of'를 사용하는 것이 가독성이 좋을 수도 있다.(관계자들끼리 규칙을 통일하면 된다.)
- 약어는 보편적으로 사용하는 것만 쓰고, 무작정 줄이는 것은 좋지 않다.
- 문법적으로 그대로 쓰기보다 중요한 단어를 앞에 쓴다. (ex totalVoc --> vocTotal)

함수 이름 짓는 순서

1. 함수가 해야 하는 기능을 문장으로 정리한다.
2. 함수는 시스템이 할 일을 나타내는 것이지 사용자가 할 일을 나타내는 것이 아니다. 따라서 함수의 주체, 주어는 필요 없다.
3. 함수의 기능을 영문장으로 작성한 후에 정관사나 불필요한 단어를 뺀다.
4. of는 앞뒤 단어를 바꾼다. (ex. sum of voc --> voc sum)
5. 소유격은 없앤다. (ex. user's name --> user name)
6. 띄어쓰기를 없애고, 두 번째 단어부터 첫 글자를 대문자로 바꾼다.
7. 함수 사용할 때 의미 없는 단어는 없앤다.

좋은 이름이 가지는 특징

검색하기 쉽고, 조합하기 쉽고, 수긍하기 쉽고, 기억하기 쉽고, 입력하기 쉬워야 합니다.

1. 검색하기 쉽게 이름 짓는 법
접두어를 활용합니다. 단, 같은 접두어를 가진 함수나 변수의 개수가 너무 많으면 안 붙이는 것만 못하므로 이런 경우에는 체계부터 다시 잡아야 합니다. (검색이 자주 필요한 상황이 아니라면 검색을 위해 접두어를 굳이 붙여야 할지도 고민해야 합니다.) 그리고 최근에는 통합개발환경이 발달해서 어떻게 검색해도 다 찾아주는데, 굳이 검색을 고려할 필요가 있는지 의문이네요.

2. 수긍하기 쉽게 이름 짓는 법
이름은 효율적으로 지어야 합니다.. 이름은 대상을 구별하기 위한 것이므로 구별할 필요가 없는 것까지 이름을 새로 지을 필요는 없습니다.. (ex. for문 내부에서만 사용되는 i, j, k 등)

3. 기억하기 쉽게 이름 짓는 법
약자를 또 다른 뜻을 가지는 단어에 맞추어 지으면 기억하기 쉽습니다. 하지만, 이미 사용하는 약자나 널리 알려진 용어는 굳이 센스를 발휘하지 말고 쓰는 것이 낫습니다.

4. 입력하기 쉽게 이름 짓는 법
오타가 잘 안나는 단어를 사용하고, 오타가 자주 나는 단어는 약자를 써도 좋습니다.

※ 오타가 자주 발생하는 단어
- 연속된 철자: successes, classes, committee, parallel
- 묵음: lambda, thumbnail, debt
- ie/ei: chief, receive, friends, achieve
- sion/tion: position, commission
- uous/ous/us: continuous, fabulous, genius

주석 쓰기

이름을 잘 지으면 주석을 줄일 수 있습니다. 처음부터 주석 없이 코딩하는 연습을 하는 것이 좋습니다. 하지만, 무조건 주석이 없는 것이 좋은 것은 아닙니다. 아무래도 한국에서 영어에 대한 이해가 사람마다 다르기 때문에 오해의 소지가 있다면 한글 주석을 달아야 합니다.

그리고, 코드에는 의미를 담고, 주석에는 코드에 담기지 않는 의도를 담습니다.
코드의 이유, 개발하면서 발견한 지식, 예상 질문과 답, 할 일, 주의, 개선 아이디어, 보완 요청, 속마음? 등을 작성합니다.

그리고, 코드의 중간부터 읽어야 하는 경우가 있다면, 동일한 주석이라도 계속 반복하여 작성할 필요가 있습니다.

수주를 돕는 SI제안서 쓰기

저는 SI제안서를 쓸 일은 없지만, 제안서를 가지고 보고할 일은 종종 있습니다. 그럴 때마다 약간 수정을 해서 보고를 하는데요. 이 부분에서 참고가 될 것 같습니다

제안서 쓰는 법

첫째, 제안 요청서 분석을 통해 기술 부분을 어떻게 써야 할지 방향을 정해야 전략적인 글쓰기가 가능합니다.
즉, 비즈니스 요구사항에 대한 이해가 되어야 이를 해결하기 위해 기술 부분을 어떻게 작성할지 전략적인 판단이 가능하다는 뜻입니다.

둘째, 제안서는 소설이 아닙니다. 이 뜻은, 제안서를 소설처럼 1쪽부터 끝까지 읽는 사람이 없다는 것입니다. 자기와 관련이 있거나, 관심 있는 특정 페이지만 읽게 됩니다. 따라서, 하나의 페이지를 읽기 위해서 다른 페이지를 참조하지 않도록 그 안에서 논리적 완결성을 갖춰야 합니다. 제가 보고서 쓰면 뒤에 내용 다 나오는데 팀장님께서 자꾸 주석 달아라, 한눈에 안 보인다 말씀하시는 게 이런 맥락이었나 봅니다. 좋은 걸 깨달았습니다.

고객의 요구사항은 변한다

고객의 요구사항은 명확하지 않고, 바뀌고 추가됩니다. 그 이유는 고객이 자기가 원하는 것이 무엇인지 정확히 모르기 때문입니다. 고객이 요구사항을 낼 때, 생각하는 모습은 구체적이지 않습니다. 그것이 설계가 되면서 조금씩 눈에 보이게 되면, 그때부터 이러면 어떨까 저러면 어떨까 새로운 아이디어가 샘솟기 시작하죠.

그래서 무릇 IT를 하는 사람이라면, 고객이 요구하는 것이 무엇인지 역으로 질문을 하고 의견을 주어야 합니다.
예를 들어, 요구사항 1,2,3 간에 논리적인 모순이 있어서 동시에 개발이 불가능하다면, 그 부분을 일깨워 주고, 일부만 개발을 해야 합니다.
혹은 고객관리 화면에서 회사 정책상 개인정보는 *로 마스킹 처리를 해야 하는데, 사업부서가 이 부분에 대한 언급을 하지 않을 수 있습니다. 이런 경우에 요구사항에 없다고 그냥 개발하면, 100% 추가 개발이 필요하기 때문에, 미리 회사 정책에 대해 알려주고, 요구사항에 넣어야 합니다.
또, 고객사에 애송이 신입이 요구사항을 냈는데, 내가 그쪽 비즈니스를 더 잘 알고 있다면, 구멍이 숭숭 뚫린 요구사항을 채워 넣고 고객사의 컨펌을 받는 식으로 적극적으로 일해야 좋은 평가를 받을 수 있습니다.

카노 모델로 본 요구의 세 가지 종류

많은 요구사항 중에 가장 신경을 써야 하는 기능이 무엇일까요?
카노 모델은 기능의 종족에 대한 소비자의 만족의 관계를 설명하는 모델입니다.
카노 모델에 따르면, 기능은 세 가지로 구분됩니다.

1. 기본 기능은 요구를 충족하지 못하면 불만이 크지만, 요구를 충족해도 고객 만족도가 크게 오르지 않는 기능입니다. 회원가입, 로그인, 로그아웃 같은 당연한 기능들입니다.

2. 기능의 성능은 요구의 충족과 고객의 만족이 비례하는 유형입니다. 예를 들어 페이지 로딩 시간이나 처리 시간 등은 시간에 비례해서 고객의 만족도가 오르내립니다.

3. 특별한 기능은 고객이 기대하지 않았던 것이어서 충족하지 못해도 불만족스럽지 않은데, 충족하면 크게 만족하는 기능입니다.

카노모델 그래프

기본 기능은 당연히 모든 요구가 수용되어야 합니다. 하지만 기능의 성능은 적정선을 정해야 합니다. 그리고 특별한 기능은 한 두 개라도 반드시 추가해야 고객의 만족을 이끌어 낼 수 있습니다. 지금 진행하는 프로젝트가 기본 기능과 성능에만 치우쳐있고, 특별한 기능이 아무것도 안 들어가 있습니다. 이 부분이 있어야 프로젝트 잘했다고 칭찬을 받겠죠?

기술 블로그 쓰기

기술 블로그 쉽게 쓰는 방법

기술 블로그는 독자의 수준이 크게 차이가 납니다. 저 같은 초보자부터 박사급까지 다양한 분들이 기술 블로그를 볼 텐데요. 따라서 기술 블로그를 독자 수준에 맞춰 쓰기란 매우 어렵습니다. 독자의 수준을 낮게 보고 기술 블로그를 쓰다 보면, 사전 지식을 설명하는데, 더 많은 내용을 할당해야 합니다. 따라서 기술 블로를 쓸 때는 독자가 아니라 자기 수준에서 써는 것이 낫습니다.
같은 맥락에서 기술 블로그는 추상적인 주제 의식이 아니라 구체적인 소재 의식으로 써야 합니다. 이는 특정 대상이나 상황에 대한 자기만의 관점이나 생각이나 해결방안을 의미합니다. 글을 왜 썼는지 독자에게 어떤 의미를 전달하는지는 고려하지 말고, 그저 사실만을 담담하게 작성해야 해야 합니다. 
그리고, 기술 그 자체를 전달하는 것도 좋지만, 그에 대한 본인의 경험이나 생각을 녹여서 좀 더 읽기 좋게 글을 쓰는 것이 좋겠습니다.

글의 종류별로 목차 잡는 법

저:직접 경험하고 실험한 과정이나 결과(개발기, 도입기, 적용기)
개발기 '목차'는 단방향이지만, 개발자의 '경험'은 양방향입니다. 개발자의 경험을 그대로 쓰면, 개발 중에 버그가 생겨서 헤매거나, 실수했던 것들까지 다 들어가게 됩니다. 따라서 중심이 되는 목차를 먼저 잡고, 버그를 해결한 경험이나, 실수했던 내용은 별도 섹션에서 문제 해결이나 팁으로 정리해 붙이는 것이 좋습니다. 여러 기업의 기술 블로그 중에서 네이버 기술 블로그가 체계적으로 잘 쓰여있으니, 참고하면 좋습니다. 저자의 추가 팁은 글을 쓸 때 본문부터 쓰고, 맺음말을 본문을 정리해서 쓰고, 마지막에 머리말을 간략히 적으라고 합니다. 개발 자니까 잘 못하는 거는 나중에 쓰라고 하네요.

술:어떤 것을 분석하여 의미를 풀이하고 해석한 것(기술 소개, 용어 분석, 에러 해결 방법 등)
대부분 제가 작성하는 것이 이쪽에 해당하겠네요. 다른 블로그나, 공식 문서, 책 등을 참고해서 작성하는 것들이 많으니까요. 이 유형의 글은 원전의 내용 그 자체를 옮겨 적는 것보다 그런 내용을 어떻게 해석하는지, 비슷한 기능을 모으거나, 반대되는 기능을 대조하면서 이해하기 쉽게 정리하는 것이 좋습니다.

편:산만하고 복잡한 자료를 편집해 질서를 부여한 것(프로그램 설치/설정 방법, 튜토리얼, 세미나 후기, 책 리뷰)
시간 순서로 일어난 일이나, 해야 할 일을 쓴 것이 많습니다. 편은 쓰기가 어렵지 않은데, 시간 순서대로 나열해 내용을 쓴 다음, "단계별로 묶어서" 요약하기만 하면 됩니다. 단계별로 묶어 주지 않으면, 장황해 보여서 글의 완성도가 떨어집니다. 

집:여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것(명령어 모음, 팁, OO규칙)
꼭 여러 사람의 견해를 다 모을 필요는 없고, 본인이 경험에서 터득한 것을 핵심만 정리한 것입니다. 어제 제가 쓴 비즈니스 용어 정리 같은 게 해당되겠네요.

 

마무리

이렇게 "개발자의 글쓰기" 내용 중, 글쓰기 기본과 변수 네이밍, 제안서 쓰기와 기술 블로그 쓰는 4가지 방법을 알아보았습니다. (릴리즈 노트, 장애 보고서, 기술 가이드는 저와 크게 관련이 없어서 읽지 않았습니다)
재미없는 내용이 될 수도 있지만, 모든 글 쓰기 방법에 대해 예시를 들어서 설명하고 있기 때문에, 글 쓰기 관련 고민이 있는 분들은 읽어보면 도움이 될 것 같습니다.

도서 정보

http://www.yes24.com/Product/Goods/79378905

개발자의 글쓰기 - YES24

저자	김철수
출판사	위키북스
출간일	2019년 10월 04일
쪽수,크기	276쪽 | 152*210*14mm
ISBN13	9791158391744
ISBN10	1158391749