요약

Tip

• 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 해라
• 일관성 있고, 개연성 있는 것이 매우 중요
• 약어 사용에 관하여
  • 누구나 이해할 수 있는 보편적인 약어는 쓰되, 그렇지 않다면 쓰지말자

서술식, 개조식, 도식

• 서술식
  • ~다로 끝나는 완성체

• 개조식
  • 명사, 용언의 명사형으로 끝냄

• 도식
  • 표로 정리

비슷하지만 다른 단어

• retrieve ; 검색해서 가져온다
• acquire ; 다른 함수가 가져가지 못하게 독점한다
• register ; 이미 정해진 틀에 값을 집어 넣는다 | create ; 정해진 틀이 없으므로 먼저 틀을 만든다
• change ; 내용을 완전히 바꾼다 | modify ; 잘못된 것을 바로잡을 때 | revise ; 새로운 정보를 덧붙여 기존 내용과 달라졌음을 분명히할 때
• parameter ; 함수에 정의한 변수 | argument ; 전달 인자(함수 호출할 때 전달하는 값)

변수명 사용 팁

• do ; 행동이 필요한 함수
• is ; bool 값 반환하는 함수

네이밍 컨벤션

• 클래스 ; UpperCamelCase
  • 주로 명사로 되어 있어 고유명사처럼 특정됨
• 함수,변수 ; lowerCamelCase
  • 함수는 동사로, 변수는 형용사로 시작하는 경우가 많음
• 상수 ; UPPER_DELIMITER_CASE
  • 값이 변해서는 안된다는 점 강조
• 패키지, 모듈 ; 소문자
• 대상의 요소나 부분을 의미할 때 ; BEM표기법(__으로 연결)
• 대상의 상태나 속성을 의미할 때 ; BEM표기법(—으로 연결)
  • 예시

.form__buton--disabled{ }

좋은 이름의 기준 ; SMART

easy to +

• Search ; 검색하기 쉽게 지어라
  • ex) ERROR_, user
• MIX ; 개발 언어의 문법과 조합해 이름을 지어라
  • ex) h1.title, h2.title, p.tilte

• Agree ; 수긍하기 쉽게 이름을 지어라
  • 수긍할 수 있는 이름 = 누가 보더라도 그렇게 짓는 것이 더 낫다고 동의 하는 이름

• Remember ; 기억하기 쉽게 이름을 지어라
  • 이미 널리 알려진 용어는 그대로 쓰는 것이 효율적이다
• Type ; 입력하기 쉽게 이름을 지어라
  • 입력할 떄 잘 틀리는 단어 ; successes, classes, committee 같은 단어들

좋은 코드에는 주석이 없다

• 이름을 잘 줄이면 주석을 없앨 수 있다.

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

→ noCreatedBecauseWrongEmail

• 이름이 길 것을 두려워하지마라. 우리에게는 자동완성 기능이 있다. 우리가 이해하기 쉽고, 구별하기 쉬운 것이 중요하다.

코드는 의미를, 주석은 의도를 전달한다.

• 코드에 표현하지 못한 어떤 의도를 전달해야 할 때는 주석을 써라.

letsEatSomething() //내가 배가 고픈 상황
letsEatSomething() //너가 배가 고픈 상황
letsEatSomething() //내가 심심한 상황

• 다른 개발자를 위해, 훗날의 나를 위해 의도를 남겨라

// TODO : ~ 기능을 추가할 것
// xxx ; null이 입력되면 무한 루프가 발생할 가능성이 있음
// 이것은 저렇게 했으면 더 좋았을 것 같다.

• 반복되는 주석도 남겨두는 것이 좋다.
  • 목차를 보고 원하는 페이지로 이동하거나 검색해서 바로 따라하는 경우가 대부분이기 때문
• 주석도 코드다.
  • 코드 리뷰를 하면서 주석 리뷰도 꼼꼼히 해야 한다.
• 에러 메시지를 쓰기 전에 에러 링크부터 없애자
  • 깨진 링크 찾아내는 서비스 ; www.brokenlinkcheck.com, 구글 서치 콘솔
• 사용자 에러 메시지 구성 ; 에러 해결 방법 → 에러 원인 → 에러 내용
• alert 메세지 ; 예 / 아니요 → ‘이 페이지에 머물기’ / ‘페이지에서 나가기’ 처럼 구체적으로 명시하기
• 사용자의 반복 에러 막는 법 ; 남은 비밀번호 시도 횟수 알려주기
• 에러메시지가 뜨지 않게 예방 메시지를 보내 에러가 뜰 수 있는 상황을 예방하라

커밋 메세지

• 너무 많이 써도, 너무 적게 써도 안좋다. 적절하게 쓰는 것이 가장 좋다.

1. 선정하기
   • 우선순위 ; 개발자가 노력을 많이들인 것 & 독자가 관심 있는것 > 노력 덜 들이고 독자가 관심 있는 것 ..
2. 분류하기
   1. 기능 추가 / 기능 개선 / 오류 수정으로 분류하기

3. 요악하기
   1. 개조식 문장으로 작성하기
4. 종합하기
   1. 핵심을 뽑아 체인지 로그의 제목으로 삼자

• 누구를 타겟으로 삼아 쓸 것인가?
  • 사용자? 개발자?
    • 사용자라면 개선으로 사용자가 얻는 혜택을 알려주라

릴리스 노트(노션)

• 문제
• 문제점
  • 문제가 일어난 원인
• 해결책
• 후속 계획

장애 보고서 쓰기

• 양식
  • 문제점 > 원인 > 해결 방법 > 해결법 > 핵심 원인 > 향후 대책
• 5Whys
  • 어떤 문제의 원인을 찾을 때 피상적인 원인이 아니라 원인의 원인, 근본적인 원인을 찾기

개발자의 글쓰기

• 개발자에게 적합한 방법 세 가지
  • 소재 우선 글쓰기
    • 특정한 대상이나 상황에 대한 자기만의 관점이나 생각이나 해결 방안

• 기술 블로그의 종류
  • 저 ; 직접 경험하고 실험한 과정이나 결과
    • 개발기, 도입기, 적용기

후기

디자인 ★★★★☆

난이도 ★★★☆☆

추천도 ★★★★☆

초반에는 나한테 조금 유익한 내용이 있었다. 네이밍 컨벤션, 변수 이름 짓는법, 주석달기 팁, 에러 메세지 쓰는 법. 그런데 뒤로 갈수록 나에게 해당되는 내용이 적어졌다. ‘고객에게 유용한 정보를 쓰는법, 개발 가이드 쓰기, SI 제안서 쓰기, 기술 블로그 쓰기’ 등

미래에 회사에 취업하게 되면, 기술 블로그를 쓰게 되면 뒷 내용도 정말 유용할 거 같다.

기술블로그는 전에 한 적이 있다. 그런데 기술블로그라고 하기에는 부끄러울 정도로 점점 기술 블로그가 아닌 복붙 블로그가 되어가고 있었다. 그 것을 깨달은 나는 그만두고 노션으로 문서화를 옮겨왔다. 다시 기술 블로그를 언젠가 할 생각이 있다. 지금은 새롭게 배운 내용들을 노션에 옮겨 적는 것만으로도 벅차다. 나중에, 내가 직접 새로운, 신기한 기능을 구현하는 날이 되면 기술 블로그를 재개할 생각이 있다.

노션 블로그는 블로그라고 하기에는 다른 블로그들과 성격이 다르다. 노션 블로그는 검색 엔진에 검색되지 않고, 직접 누군가에게 링크를 공유해주어야 읽을 수 있는 형태이다.

현재 나의 노션 블로그는 메모용이다. 이런 메모들이 쌓이고 쌓여 뒤돌아 보았을 때 ‘아, 나 잘하고 있구나. 많이 했구나.’ 라는 생각이 들기 용도라 보면 된다. 그리고, 내가 원하는 정보를 원하는 형태로 가공하여 저장하여 쉽게 찾을 수 있어서 좋다.

책 본론으로 들어가보면, 책에서는 제목 그대로 개발자의 글쓰기에 관해 다루고 있다. 개발자들은 공통적으로 글을 잘 못 쓴다고 한다. 하지만 우리는 글을 써야하고, 써야 하는 직업이다.

일단 나에게 가장 와닿았던 것은 변수 네이밍이다. 변수, 지을 때마다 고민되고 싶지 않은 녀석이다. 변수는 내공이 쌓이고 쌓여야 하는 것 같다. 어떤 상황에서는 어떤 변수를, 어떤 용도에는 어떤 변수를 짓는 것이 경험에서 우러나오더라. 작자는 이렇게 말한다.

간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 해라 일관성 있고, 개연성 있는 것이 매우 중요하다. 누구나 이해할 수 있는 보편적인 약어는 쓰되, 그렇지 않다면 쓰지말자. 이 또한 일관성이 중요하다.

본인만의 변수명 규칙을 정해놓는 것이 참 좋을 것 같다. 예를들어 동작을 하는 변수에는 on 혹은 do를 붙히고, bool값을 나타내는 변수에는 is를 붙히는 식으로 말이다.

그리고 어떠한 변수냐에 따라 함수 명에는 lowerCamelCase, 컴포넌트 명에는 UpperCamelCase, class명에는 Bem(—,__)표기법을 쓰는 것처럼 말이다.

변수를 길게 하더라도, 변수에 해당 변수가 어떤 역할을 할지 명시되어있다면 주석을 달지 않아도 된다. 그래서

좋은 코드에는 주석이 없다.