[도서 리뷰] 개발자의 글쓰기 - 김철수 지음

책 내용

1. 개발자가 알아야 하는 글쓰기 기본

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

핵심을 먼저 말한 뒤, 필요에 따라 부가 설명을 한다.

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

 

개조식 방식 + 글머리 기호를 활용한다. 서술의 목적에 따라, 들여쓰기와 번호에 위계를 맞춰야 한다.

비즈니스 문서도 마찬가지로 문단간의 위계 + 탭과 같은 스타일과 계층이 필요하다.

읽기 쉽기 위해서는 계층이 필수!

 

비즈니스 문서 문장 부호

큰따옴표 "" : 책의 제목, 신문 이름

작은따옴표 '' : 소제목, 예술작품의 제목, 상호, 법률, 규정. + 강조, 비교

 

외래어, 영어

함수 선언 시 반대되는 단어를 사용하자. 프로그램 안에서 일관성, 개연성의 합의가 될 정도로 통

일하는 것이 중요하다.

 

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

네이밍 컨벤션

창조가 아니라 조합! 규칙에 따라 잘 조합하면 된다.

영어 표기법 - 파스칼 & 카멜 : 영어의 대문자 표기 원칙 상속

1. 중요하거나 크거나 특정한 것을 가리키거나 제목에 해당하는 명사 - 첫글자 대문자
2. 그런 명사들이 이어질때 첫글자 모두 대문자
3. 명사, 관사가 아닌 동사, 형용사 등은 소문자를 쓴다.

 

파스칼 표기법 : 첫글자 대문자. 클래스 & 인터페이스 이름에 주로 사용

→ 프로그래밍에서 가장 주요하고, 높은 위치. 고유명사처럼 특정되며 명사로 되어있다.

→ 명사 여러개를 뭍여 쓰는 경우 각 명사의 첫글자를 모두 대문자로 쓴다.

포함하는 큰 개념, 고유명사나 호칭 같은 경우

 

카멜 표기법 : 첫글자 빼고 나머지 단어의 첫글자 대문자. 함수 & 변수 이름에 주로 사용

함수는 동작을 시키는 명령어 개념으로 - 동사

변수 - 형용사

 

상수 : 모두 대문자, 언더스코어 _ 로 단어를 연결

값이 변해서는 안된다는 점을 강조, 주의하기 위해 가독성을 위한 대문자를 사용했지만,

통합개발환경 IDE 가 발샌해서 굳이 상수를 모두 대문자로 쓸 필요가 있는지 의문이다. 개인의 자유이지만 회사 내에서 통일하는 것이 좋다.

 

패키지 & 모듈 : 모두 소문자

클래스나 함수보다 더 높은 위치가 될텐데, 실제로는 소문자만 쓴다. 이들은 클래스를 모으거나 함수를 담아놓은 통에 불과하기 때문이다.

또한 패키지, 클래스 이름이나 모듈, 함수 이름을 헷갈릴 수 있어서 모두 소문자로 쓰기로 결정했다.

 

BEM block, element, modifier 표기법 : CSS 에서 사용하는 표기법 `대상--요소__상태`

대상의 요소나 부분을 의미할때 언더스코어 두개로 연결한다. 이것들의 상태나 속성을 의미할 대는 하이픈 두개--로 연결한다.

 

뭐가 어떻든 가독성과 소통이 먼저다!

따라할 것이 아니라, 그렇게 쓰는 이유를 알고 써야 한다!! - 내 가치관과 유사하다

요즘은 개발툴이 많이 발전되어서, 대소문자와 무관한 색상으로 가독성을 챙길 수는 있다. 그러나 소통은 컨벤션이 중요하다. 변수나 함수명에 따라 의미하는 바에 대한 이해도를 통일하기 위해 컨벤션 규칙을 챙기는 것이 매우 중요하다. `가독성`, `소통`

 

변수 이름을 잘 짓는 법

오픈소스 네이밍 특징들 → 가낭 많이 쓰는 변수 이름 → i, LOG, result

a, d 처럼 의미없는 글자를 변수로 쓰는 것은 좋지 않다. 변수 자체를 보고 의미와 데이터를 파악할 수 ㅣㅇㅆ는 정보를 담아야 한다.

 

긴 이름, 짧은 이름이 중요한게 아니다! 👍 검색 잘 되는 이름 👍

과거는 오탈자 때문에 길이가 문제가 될 수 있었지만, 개발도구가 검색해서 알려준다. 변수 이름의 길이와 오탈자의 상관관계는 이제 없다.

변수 접두어 - m, n, is, btn, img 등등의 헝가리안 표기법 유익했지만, 개발도구가 변수 타입이 자동으로 표시되기 때문에 레거시라고 봐도 됨

그래서 약어를 쓰는게 좋은지? 안좋은지? → 서비스 이름, 패키지 이름, 클래스 이름에 약어 사용 정도 👍 (AWS S3 등) 

보편성을 기준으로 선택하는게 중요하다. 보편적으로 이해할 수 있는 정도

 

복수형은 언제 사용?

배열이나 여러개의 변수명을 가리킬때 종종! 그런데 함수명 중간에는 s 가 명확히 눈에 보이지 않기 때문에, array 나 listof 과 같은 표시방법을 사용하기도 한다.

 

중요한 단어를 앞에 쓴다.

totalVisitor 의 경우 - total 보다 visitor 을 먼저 검색하는 경우가 있으니, visitor 가 중요하다! 중요한 것이 앞에 와야 한다.

개발도구가 자동으로 찾아주기 때문에 큰 문제가 생기지는 않겠지만, 기본 원칙으로 생각하자

 

좋은 이름의 기준 SMART

easy to

• Search : 검색
  • 검색에 유용하게 도입! 한단계 상위 범주의 이름을 접두어로 태그처럼 사용!
• Mix : 조합
  • 태그, title 과의 조합으로 h1, p 태그의 스타일링에 모두 사용할 수 있음
• Agree : 수긍
  • 누가 보더라도 그렇게 짓는 것이 더 낫다!
  • 특정 함수 안에서만 일시적으로 사용된다면, 길거나 구체적인 새로운 이름을 지을 필요가 없다.
• Remember : 기억
  • 시청각적으로 연상어를 떠올려서 기억할 수 있도록
  • 이미 널리 알려졌거나, 익숙한(익숙해진)것들은 그냥 쓰자
• Type : 입력
  • 연속된 철자, 묵음, ie/ei, sion/tion,. uous/ous/us 잘 틀리는 예시

 

이름 잘 지으면 주석 줄일 수 있다!

주석없이 코드짜는 연습을 하자~

이유를 알려주거나, 성능 등 새롭게 발견한 것, 예상 질문과 답, todo, 주의 xxx, hack 개선 아이디어 주기, 협업 보완 요청, 속마음 등을 자유롭게 표현할 수 있다.

코드 업데이트와 동일하게 주석도 잊지않고 업데이트 해주기! 잘못된 데이터가 있을 수는 없다.

 

3. 사용자와 소통하는 에러 메시지

404 에 대하여 구글은 아주 심플하게 설명한다.

한국 사이트들은 아주 상세하게 설명하거나, 고객센터를 연결한다.

 

404 의 경우

1. 사용자가 잘못된 링크를 입력

2. 클릭했는데 없는 페이지

1번은 안죄송해도 되지만, 2번은 죄송해야 한다. 없는 페이지를 유지하는 것을 깨진 링크, 죽은 링크, 나쁜 링크라고 한다. 애초에 이 링크가 없도록 관리하는게 맞음. 

 

개발자용 에러메시지 / 사용자용 에러메시지  분리해 작성해라! → Kampus 프로젝트에서의 개선점

C 의 #define 전처리기를 사용해 메크로로 한번에 처리할 수 있다.

 

예외처리 작성법

오류의 내용과 원인 고지 - 예외처리

에러 메시지의 목적 : 사용자에게 에러가 발생했음을 고지. 즉 사용자가 해결해야 하는 부분이 기때문에, 해결방법이 추가되어야 한다.

 

발생 원인이 긴 경우에는 1. 해결방법 2. 에러 원인 3. 에러 내용 순서로 말하는게 낫다.

예, 아니오 버튼으로 구성하지 않고, 행동에 대해 구체적으로 서술하는 버튼을 유지하는게 좋다. (ex. 나가기, 변경하기 등)

 

확인, 취소 위치의 경우, 서비스 내에서 명확한 일관성을 따르는 것이 좋다. 

 

비밀번호 여러번 입력으로 인한 해킹공격을 방지하기 위해 로그인 입력횟수를 제한하는 것도 좋다.

 

에러메시지 대신 예방 메시지를 사용하자

ex. 캘린더 날짜 선택에서 지난 날짜는 선택할 수 없는 상황

1. 지난 날짜를 선택하면 alert 경고창으로 지난날짜를 선택할 수 없다고 한다

2. 지난 날짜 선택이 불가능하도록 막아놓는다. (비활성화)

 

💡 사용자가 첫 번째 select에서 선택한 값에 따라 두 번째 select의 선택 옵션을 동적으로 제한하는 것은 가능한가??

이 의문에 대해 블로그 글 추가 작성 예정! `싱크스팟 시간투표 로직`

 

재확인 + 취소 여러 요청이 많아 혼돈됨

 

1. 재확인 : 사용자의 의사결정을 믿을 수 없다고 본다. 할수 있는 모든 경고를 함

2. 결제 직후 취소버튼 표출 : 사용자가 자신의 행동을 주체적으로 책임지게 한다

모든 결정에 재확인을 한다면, 시스템도 불완전해질수밖에 없다.

꼭 필요한지 검토하고 수행하자. 개발자의 철학에 달렸다.

 

4. 릴리스 문서, 장애 보고서 - 독자 관점

체인지로그 changelog 너무 짧지도, 길지도 않게!

1. 내용 선정하기
   • 개발 + 독자 + 회사의 입장 고려해서 선정
2. 비슷한 로그끼리 분류
   • 개발 관점의 작업 (ex. 기능 추가, 기능 개선, 오류 수정) → 독자 : 개발자인 경우
     • 소프트웨어 릴리스 문서에서 사용
   • 사용자 관점 (ex. 게임 준비, 게임 중, 게임 종료) → 일반 사용자인 경우
3. 문장 단위로 요약 : `개조식`
4. 핵심 한문장으로 종합하기
   • 각 대표 작업의 핵심 단어를 추출해서 조합한다. 기술적 내용보다는 행위의 목적을 요약하는 바!
   • 내용이 두가지 이상이면, 줄을 분리한다

 

예문 정리본

사용자 편리성 개선

• 게임방에 더 빨리 입장
• 게임 결과 바로 확인

[세부 내용]

• 게임 준비
  • 미리 보기 리부팅 문제 해결
  • 빈 게임방 자동 검색 기능 추가
• 게임 중
  • 고해상도 폰에서 아이콘이 찌그러지는 오류 수정
  • 애니메이션 스티커가 멈추는 오류 수정
• 게임 종료
  • 최근 기록이 상위에 올리오도록 개선
  • 용량이 큰 사진을 등록할 때 메모리 사용 최소화

 

체인지 로그는 고객을 위한 것

고객에게 끼치는 영향 작성

개발자 문제 + 고객의 문제를 합치되, 고객의 문제를 앞쪽, 개발자의 문제를 짧게 개조식으로 표현한다

개선점에 따라오는 고객의 효과, 혜택을 분명하게 이야기 해야 한다.

기능 사용을 유도하는 문장도 굿 👍

only 고객만이 아닌, 개발자의 문제도 함께 기재해도 좋다

검토중인 항목을 기재해서, 서비스 현황을 알리는 방식도 좋다.

 

태그 버전을 올리는 명확한 기준이 없음

깃허브 Semantic Versioning 제시함

유의적 버전 2.0.0

X.Y.Z

• `X` Major `Y` Minow `Z` Patch
• X : 0인 것은 초기 내부 개발에서만 사용. 최초 공개는 1.0.0 이어야 한다.
• Y : 기존 버전과 호환되는 새로운 기능 추가. 큰 규모의 패치
• Z : 작은 규모의 패치. X, Y 를 올리면 Z 는 0 으로 초기화 되어야 한다.
• pre release 사전배포가 필요한 경우 `X.Y.Z-alpha.1` 과 같은 식별자 사용한다
• 배포된 버전은 변경해서는 안된다. 변경이 있다면 버전을 올려야 한다.

태그 배포 도입한 경험!

 

릴리스 문서 (노트) = 문제 해결 보고서

• 문제 : 사용자가 급증하면 서버가 정지
• 문제점 : 잘못된 시스템 설정, 프로그램 비 최적화, 잘못된 DB 설계
• 해결책 : 시스템 설정 변경
• 후속 계획 : 프로그램 최적화, DB 재설계

서술형으로 작성해도 됨.

 

법적인 문제도 고려하기 - 보고서의 형식

• 문저 정보 : 제품명, 릴리스 이름, 버전, 날짜 등
• 개요 : 종합 글
• 새로운 기능
• 개선사항
• 버그 수정
• 영향과 주의사항 : 릴리스로 인한 영향과 개발자의 주의사항
• 연략서 : 문의나 의견 접수를 위한 담당자 이름과 연락처 정보
• 면책 : 법적 문제 발생 시 책임의 한계에 관한 내용

어떠한 행동을 유도할때 필수, 권장, 선택인지 명확히 서술어로 구분해야 한다.

예외 사항을 명시해야만 면책될 수 있다.

 

비즈니스 장애 보고서

1. 질문에 대답하는 신속한 글쓰기
   • 대화식 → 개조식
   • 장애 내용, 영향, 원인, 상황, 결과, 핵심 원인, 향후 대책
2. 원인과 이유를 찾는 분석적 글쓰기
   • 5 Whys
   • 사물, 현상, 동작이 문제를 초래하는 원인
   • 사람이 문제를 초래하는 원인 → 대다수 재발의 원인
     • 소통의 문제 → 여러사람 참조로 해결 가능
3. 상사를 고려하는 비즈니스 관점의 글쓰기 (비개발자)
   • 결제 뿐만 아니라 접속 기능 실패일때도 → 기대 매출 손실 결과에 도래할 수 있다.
4. 원하는 것을 얻는 정치적 글쓰기
   • 비즈니스는 확정적인 대답을 원한다. 의사 결정의 어려움
   • 예산, 추후 행동을 예상하여 정확한 단어와 문장으로 현상과 사실을 그대로 표현해야 한다.

 

5. 개발 가이드 - 설명, 묘사, 논증, 서사

• 범주 : 서비스의 용도. 유사서비스와 차별화하는 특징 설명을 통해 서비스의 개념을 정확히 이해한다.
  • 단어를 명확하게 선정해야 한다. 유사 서비스 설명 참고. `일종의` `발전된` `개발자를 위한`과 같은 수식으로 차이점을 줄 수 있음
• 용도 : 독자 관점에서 이 서비스를 이용하는 이유. 
  • 서비스의 핵심 기능일 수도 있지만, 범주의 핵심 기능일 수도 있다.
  • 개발자 측면에서 조금 더 추상적일 필요가 있다.
• 특징 : 타 서비스와의 차별화, 장점 + 강점
  • 장점 - 본인 기준
  • 강점 - 경장사 비교
  • 둘을 합친 것이 특징이 된다

 

글, 그림, 도식화, 사진을 통한 묘사도 효과적!!

협업 시에는 비개발직군의 주관적 묘사 → 객관적 묘사로 변경하여 논의 → 개발에 필요한 주관적 묘사로 업그레이드 하는 것이 좋다. 주도권을 가지고 논의하면 추후 수정사항이 단축될 것이다.

 

의견에 필요한 것 `근거` 를 활용해서 논증하자.

👍 개발자가 직접 체험한 결과를 기반으로 하는 주장

너무 거칠거나, 공손하거나 중립적 XXX 확신이 없어 보인다.

~ 하십시오, ~하지 마십시오 의 표현을 활용하자.

 

`주장 - 이유` 와 `문제 - 답` 의 거리를 가깝게 작성하자.

 

서사 : 화면의 흐름에 맞게 설명하는 것. 시간, 중요도 등

순서 → 단계 → 목차 로 정돈하여 글을 읽기 쉽게 함

 

6. 기술 블로그 쉽게 쓰고 운영하기

과거 글쓰기 = 문제해결 과정으로 학습했다.

문제를 충분히 고민하고, 해결 방안을 전략적으로 작성하는 흐름

논리의 부족함이 있다면, 근거가 완벽해질 때까지 쓰지 말것

 

1. 주제 의식 X 소재 의식 O
   • 개발자의 기술블로그의 첫번째 목적은 `개발 과정 기록` 이다. 강렬한 주제의식이 필요한 것이 아니다.
   • 소재 의식 : 대상이나 상황에서 맞닥뜨렸을 때부터 ~ 벗어날 때까지 겪은 일을 담담하게 정리
   • 수필 즉 그저 일어난 이야기를 설명하는 것과 유사함. 내용 공유의 목적
2. 독자 수준 X  자기 수준 O
   • 독자를 고려한 비유법보다, 내가 이해하기 위해 생각한 비유법 정도는 괜찮다.
   • 독자를 위해 설명하다가 정작 소재 의식에 대한 내용보다 주객전도 될 수 있다.
   • 필요하다면 공식문서의 링크를 첨부하자.
3. 재미있게! 글을 쓰기
   • 경험, 기교를 사실과 적절히 혼합한다.
   • 독자가 공감하고, 고개를 끄덕일 수 있게 해야 한다.

 

저, 술, 편, 집 - 기술 블로그 유형 4가지

1. 저 : 직접 경험하고 실험한 과정이나 결과
   • 개발기, 도입기 적용기
   • 목차 중요함 : 1차원 단방향
   • 성공 / 실패 루트를 구분한다.
   • 성공 최종 루트 이후 → 실패 문제해결 팁 정리
     • 본인의 경우, 개발 경험 흐름에 맞춰서 작성하는게 일반적이었다. Flat config 에 대해 작성한 내용이 대표적이다. 참고한 글 흐름
     • 나의 경험을 알리기에는 최적이지만, 결과를 보러온 독자들에게는 불편할 수도 있겠다는 생각이 든다.
     • 책의 방식도 점진적으로 적용해보자!!
   • 본문 → 맺음말 → 머릿말 순서로 작성하자. 머릿말은 간략히 적는다.
2. 술 : 어떤 것을 분석하여 의미를 풀이하고 해석한 것
   • 기술 소개, 용어 분석, 에러 해결 방법 등
   • 본래 내용을 바탕으로 자신의 분석이나 해설을 덧붙이는 방식
   • 정리만 한다면 경전이 될것! 여기에 자신만의 방식으로 풀이하는 게 필요하다.
3. 편 : 산만하고 복잡한 자료를 편집해 질서를 부여한 것
   • 프로그램 설치 설정 방법, 튜토리얼, 세미나 후기, 책 리뷰
   • 시간 순서대로 요약해서 나열
   • 전체 내용의 목차를 잘 구조화 하는 것이 필요하다.
4. 집 : 흩어진 자료를 한데 모아 정리한 것
   • 명령어 모음, 팁, 00가지 규칙
   • 편집된 글 모음. 주로 조회수가 높다 ㅋㅋㅋ

 

기업의 기술 블로그 운영

1. 개발자 수준을 높이고, 채용과 연관이 깊음
2. 노하우를 체계적으로 축적할 수 있다. 일종의 사내 문서 관리가 된다
3. 개발자가 꾸준히 스스로 공부하도록 한다.

회사의 문화를 반영한다. 각 기업마다 문서의 구조가 다른 편이다.

회사의 교육 수준 → 개발자의 개발 수준

Pari Writing 짝 글쓰기

• 서로 독자 관점에서 질무하면서 완성도가 높아진다.
  • 코드리뷰의 질문을 문서에 반영하는 방법도 있음
• 공통된 지식 체계는 훨씬 보편적인 편이다.
• 자연스러운 팀 회고가 된다.
• 부담과 중압감에서 가볍다고 느낀다. 심리적 안정감
• 팀워크, 소통 향상

 

🧐 느낀 점

최근에 내가 글을 잘 쓰고 있는지 고민이었다. 개발의 비중보다, 글쓰기의 비중이 높아져서 혼란스럽기도 했다. 과거 다독왕 경험을 살려 도서관에서 책을 고르는 도중에 만난 책이었다.

 

책을 읽으면서 내가 고민하던 부분에서 나아가는 방향이 맞았다는 확신을 가지게 되었다. 특히, 개발자와 디자이너 간의 협업에서 발생할 수 있는 소통의 문제를 해결하기 위한 글쓰기의 중요성을 깨달았다. 예를 들어, 함수와 변수 이름을 짓는 것부터 시작해, 주석을 어떻게 작성해야 하는지에 대한 구체적인 팁들이 인상 깊었다. 이러한 세부적인 내용들이 실제로 협업을 할 때 큰 도움이 될 것이라는 생각이 들었다.

또한, 더 좋은 DX, UX 등 협업관계를 구축하기 위해 고려할 점에 대한 설명을 통해 변화하고 개선하는 것이 좋겠다고 느꼈다. 글쓰기가 단순히 정보를 전달하는 수단이 아니라, 팀원 간의 이해를 돕고, 프로젝트의 성공을 이끌어내는 중요한 요소라는 점을 다시 한번 상기시켰다.

마지막으로, 개발적으로도 개선할 점을 찾은 부분이 많았다. 코드의 가독성을 높이거나 에러 처리 방식, 그리고 팀원들이 쉽게 이해할 수 있도록 정보를 전달하는 방법에 대해 많은 인사이트를 얻었다.

 

중요한 것은 `글쓰기는 단순한 기술이 아니라 소통의 도구`라는 것이다. 개발자라면 코드뿐만 아니라 그 코드에 대한 설명과 의도를 잘 전달할 수 있어야 한다. 이 책을 통해 글쓰기의 중요성을 다시 한번 깨닫고, 앞으로의 개발 생활에 큰 도움이 될 것 같다.