📚 개발자의 글쓰기

제목	독서일	출판사
개발자의 글쓰기	2022/03/10	위키북스

문장, 단락 구조화

• 글로 표현하는 3가지 방법
  1. 서술식: ‘~다.’ 로 끝나는 완전한 문장으로 구성.
     • 순서, 단계를 나타낼때 1, 2, 3, 가, 나, 다 등을 이용.
     • ex) 소설, 신문기사, 개발 가이드 문서
  2. 개조식: 사항을 나열함. 명사형으로 끝남. 글머리 기호 필수.
     • 글머리 기호의 종류
       • 설명: 구체적인 내용 설명, 나열 시, •, ∘, √, ※, *, □, ■ 기호 사용
       • 하위 일 수록 증요도 ↓ 들여쓰기와 크기 조절.
     • ex) 신문 헤드라인, 릴리스 문서, 장애 보고서
  3. 도식: 그림이나 서식으로 보여줌.
     • 내용을 그림으로 나타낼 때, 영역을 ① 원형 숫자로 표시.
     • ex) 표(글), 도표(그림)
• 단락을 구조화 하는 위계
  • 위계 : 위치와 계층을 합친 말.
  • 위계는 굵기와 밑줄 등으로 나타낼 수 있다.
• 문장 부호
  • 책 제목이나 신문 이름 등은 " "을 사용.
  • 소제목이나 예술 작품 제목, 상호, 법률, 규정, 강조하거나 비교해서 드러내야 할 때는 ' '을 사용.
• 영어 단어 선택과 외래어 표기법
  • 이미 굳어진 외래어는 관용을 존중하되, 그 범위와 용례는 따로 정한다.

이름 짓기, 주석 쓰기

명명 규칙

명명 규칙은 팀 내 규칙이 정해져있으면 사내 규칙을 따른 것이 좋다. 팀원끼리 코드 컨벤션을 잘 지켜서 코드를 짠다면 유지보수가 좋아진다.

• 파스칼 표기법으로 클래스 이름 짓기.

  interface Menu
  Class CoffeeMenu implements Menu
  

• 카멜 표기법으로 함수, 변수의 이름 짓기.

  let totalCount = null;
  

• 상수는 모두 대문자로 쓴다.

  const TOTAL_COUNT = null;
  

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

  import developerwriting
  

• BEM 표기법.

  .form__button {
   ...;
  }
  

변수 이름을 잘 짓는 법

1. 의미없는 글자를 변수명으로 짓지 말자.
2. 검색이 잘 되는 이름으로 변수명을 짓자.
3. 약어는 보편적으로 사용 되는 것을 쓰자.
4. 중요한 단어를 앞에 쓰자.

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

1. 검색하기 쉽고

고전적 범주화(특정 대상들을 묶어 상주 범위를 만들어 이해하는 것)를 이용해 한 단계 상위 범주의 이름을 태그처럼 덧붙이면 된다.

1. 조합하기 쉽고

개발 언어의 문법과 조합해 이름을 지으면 쉽다.

1. 수긍하기 쉽고

대상을 구별할 필요 없다면 이름을 새로 지을 필요가 없다 (ex. for문의 i, j, k처럼)

1. 기억하기 쉽고

널리 알려진 용어는 그냥 쓰는 것이 효율적이다. (ex. Hello World)

1. 입력하기 쉽고

연속되는 철자는 주의하자.

주석은 무조건 나쁠까?

주석은 같이 개발 하는 사람들과 소통을 할 수 있고 더 좋은 코드를 공유할 수 있는 좋은 수단이라고 생각하지만 너무 많이 쓰게 되면 코드를 읽는데 방해가 될 수 있다.

주석이 제 역할에만 충실 하다면 많고 적고는 상관없다. 코드는 의미를, 주석은 의도를 나타나게 쓰면 된다.

에러 메세지

에러 메세지 순서

1. 에러 내용: 오류로 인한 문제와 종류
2. 에러의 원인: 오류를 발생시킨 직접적이고 근본적인 원인
3. 에러 해결 방법: 사용자가 오류를 해결할 가장 쉽고 빠른 방법

원인과 내용이 복잡할 땐 방법부터 보여주는 것도 좋다.

에러 메세지보다 예방 메세지를 쓰자

예를 들어 호텔 예약 시 한 달 까지만 예약을 할 수 있다면 날짜를 선택 할 때 한 달 뒤는 disable 처리를 하는 것도 좋은 방법이다.

버튼을 활용

버튼을 사용할 때, 확인 또는 취소만 쓰기보단, 다음 취할 행동을 말해주는 것도 좋다 예를 들면 페이지에서 나가기 같이.

릴리즈 문서 쓰기

릴리즈 문서 쓰는 단계

1. 선정하기

   사용자가 듣고 싶고, 회사가 말하고 싶고, 개발자가 알리고 싶은 체인지 로그를 선정하자.

2. 분류하기

   개발 관점에서 비슷한 작업으로 묶는 방법 - 보통 소프트웨어 릴리스 문서에서 사용하는 새로운 기능 추가, 기능 개선 오류, 수정으로 묶을 수 있다. 사용자 관점에서 비슷한 것끼리 묶는 방법

3. 요약하기

   문장 단위로 요약, 서술식 문장을 개조식 문장으로 바꾸는 방법을 쓰면 내용이 자연스럽게 축약되고 의미는 분명해진다.

4. 종합하기

   내용 전체를 종합해서 한 문장으로 만들고 그것을 체인지 로그 첫 줄에 적는다. 단, 내용을 종합할 때는 핵심이 되는 내용들만 발췌해서 종합한다. 체인지 로그 선정하기 에서 1순위로 선정했던 로그를 발췌하는 것이 좋다.

서평

필자가 이 책을 산 이유는 개발자가 생각보다 글을 써야할 일이 많다고 느껴 조금이라도 도움이 되고자 구매하게 되었다. 이 책은 글 뿐만 아니라 주석, 변수명명규칙에 대해서도 말하고 있는데 이름을 짓는 것이 어려운 일 중 하나라고 느끼는 필자에게 많이 도움이 되었다.