개발자의 글쓰기

시작

많은 개발자들이 어려움을 겪고있는 문제

개발 하면서 느끼는 문서의 중요성

주석

1. 되도록 주석이 필요 없게끔 하되, 한번에 파악하기 어려운 곳에는 주석을 작성한다.
2. API문서를 볼 때 검색해서 예제를 보고 따라하는 경우가 존재한다.
   • 이런 독자를 위해서는 같은 주석이라고 해도 반복해서 쓰는게 좋다.
   • 반드시 반복되는 주석을 지워야만 좋은 것은 아니다.
3. 잘못 쓴 주석은 잘못 쓴 코드보다 리스크가 훨씬 크다.
   • 주석 리뷰의 필요성
   • 꼭 필요한 주석만 달기

변수 이름 잘 짓는법

1. 변수 이름 선택, 외래어 발음 선택등에 있어서는 결국 그룹의 개연적인 합의와 컨벤션 규칙이 우선이다.
   (정해진 답은 없다는 뜻)
   - 약어는 보편성을 기준으로
   - VIPDM (X) / VeryImportantPersonDataManager (X) / VIPDataManager (O)
2. '검색 잘되는 이름' 을 생각하면서 정한다.
   • 한 단계 상위 범주의 이름을 태그처럼 붙이는 방법
     • ERROR_SERVER_TIMEOUT
     • ERROR_BAD_REQUEST
3. 중요한 단어를 앞에 붙이는 방법
   • totalVisitor (X) visitorTotal (O)
   • 검색할 때는 visitor 로 검색하게 되기 때문

중요한 5요소는 다음과 같다. (SMART)

• 검색하기 쉬움 → easy to Search
• 조합하기 쉬움 → easy to Mix
• 수긍하기 쉬움 → easy to Agree
• 기억하기 쉬움 → easy to Remember
• 입력하기 쉬움 → easy to Type

에러 메시지

ex ) 회원가입을 할 때 휴대폰 번호를 잘못 입력 한 상태로 확인이나 다음 버튼을 클락하는 경우

• 휴대폰 번호를 잘못 입력하셔서 회원가입을 진행할 수 없습니다.
  휴대폰 번호 입력란에는 숫자만 입력하십시오.

• why

  • 에러내용 : 오류로 인한 문제와 종류
  • 에러의 원인 : 오류를 발생시킨 직접적이고 근본적인 원인
  • 에러 해결 방법 : 사용자가 오류를 해결할 가장 쉽고 빠른 방법
  • 에러내용 : 회원가입을 진행할 수 없습니다.
  • 에러의 원인 : 휴대폰 번호를 잘못 입력하셨습니다.
  • 에러 해결 방법 : 휴대폰 번호 입력란에는 숫자만 입력하십시오.

• 지금 이 페이지를 떠나면 편집한 내용이 취소될 수 있습니다. 취소하시겠습니까?

  • 예 or 아니오
    • 예 버튼 클릭시 어떤 결과가 벌어질까?
      • 편집한 내용이 취소돼서 다른 페이지로 이동할까?
      • 편집한 내용이 취소될 수 있으니 이 페이지를 떠나는 행위를 취소할까?
    • 아니오 버튼 클릭시 어떤 결과가 벌어질까?
      • 이 페이지를 안떠나겠다는 것일까?
      • 편집한 내용을 안 쓰겠다는 것일까?

  ⇒ 변경 가능한 방법

  • 질문을 변경
    • 편집한 내용을 삭제하고 다른 페이지로 이동하시겠습니까?
    • 버튼 텍스트를 ‘예’ 또는 ‘아니오’말고 역할에 맞는 특정한 행동을 유지하게 텍스트 넣기
      • 예 ⇒ 삭제하고 이동하기 / 아니요 ⇒ 계속 편집하기
  • ex) 페이스북
    • 질문 : 페이지를 나가시겠어요? 아직 글을 올리지 않았습니다. 올리지 않고 나가시겠어요?
    • 버튼 : 이 페이지에 머무르게 / 페이지에서 나가기