[책] 개발자의 글쓰기

개발자가 알아야 할 글쓰기 기본

• 문장을 만드는 방법은 다양하므로, 문장을 어떻게 만드느냐 도 중요함.

• 개발자의 생각을 글로 표현하는 데는 크게 세 가지 방법이 있다.

  • 서술식)

    • '~다'로 끝나는 완전한 문장으로 구성된 글.
    • 무엇을 '설명'하거나, '논증'할 때 주로 사용.
    • 줄거리가 있는 설명 혹은 이야기라면 서술식을 사용.

  • 개조식)

    • 신문의 헤드라인 혹은 어떤 사항을 나열할 때 사용.
    • 여러 가지 종류의 항목과 내용이 반복되거나 서술식에서 강조가 필요한 내용이라면 개조식을 사용.
    • *글머리 기호를 꼭 써야 함 ! (ex. 네모, 동그라미, 점, 막대 등)
    • 지금 내가 쓰는 것도 개조식에 해당

  • 도식)

    • 사물의 구조나 관계, 상태를 '그림'이나 '서식'으로 보여주는 것.
    • 쉽게 말해 행과 열로 이루어진 표도 도식이며, 그 행렬에 막대 같은 그림이 있다면 우리가 아는 '도표'라고 한다.
    • 각 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식 사용.

• 개발을 하다 보면, 반대되는 영어 단어를 선택해야 할 때가 많음.
  • ex) HTML에서 어떤 레이어를 보여주고 감출 때, show와 hide라는 반대말을 정확히 사용해야 함.
    -> show를 썼는데 hide 대신 invisible을 쓰면 안됨. 두 단어는 서로의 반대말이 아니기 때문 !

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

• 아무리 작은 프로그램이나 간단한 애플리케이션이라도 수많은 이름을 지어야 함.

• 변수 이름부터 함수, 클래스, 하다못해 프로젝트 명까지 결정해야 함.

• 지어야 할 이름이 많아서 머리가 아프겠지만, 이름을 잘 지어놓으면 코드를 짜기도 쉽고 이해하기도 쉽기 때문에 중요한 부분 중 하나임.

  • 파스칼 표기법)

    • 모든 단어에서 첫 글자를 대문자로 씀.
    • 주로 클래스 이름에 사용하는데, 클래스가 프로그래밍에서 가장 주요하고 높은 위치에 있고, 고유명사처럼 특정되며, 명사로 되어 있기 때문.

  • 카멜 표기법)

    • 첫 단어를 제외한 나머지 단어의 첫번째 글자만 대문자로 씀.
    • 주로 함수, 변수에 사용하는데, 함수는 동작을 시키는 '명령어'개넘이므로 첫 단어가 주로 동사이며 변수는 형용사로 시작하는 경우도 많다.
    • 영어 표기 원칙의 기본은 명사가 아닌 경우 첫 글자를 소문자로 시작 한다는 것이므로, 함수와 변수가 이에 해당됨 !

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

    • 상수는 값이 변해서는 안된다는 점을 강조 및 주의시키기 위해 가독성을 높이는 방법으로 대문자를 사용한다. (요즘엔 굳이 대문자로 쓸 필요 없어서 각 회사 규칙에 따르는 추세라고 한다.)

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

    • 패키지와 모듈은 클래스나 함수를 담아놓은 통에 불과하므로 소문자로 씀.

• BEM 표기법)

  • CSS에서 사용하는데, 대상의 '요소'나 '부분'을 의미할 때는 언더스코어 두개 __ 로 연결한다.
  • 대상이나 요소의 상태나 속성을 의미할 때는 하이픈 두 개 -- 로 연결한다.

• 약어를 쓸까 ? 말까 ?

  • 개발자마다 추천 여부는 다르지만, 해당 책의 필자는 약어 사용에 대해 긍정적.
  • 편하기도 하고, 보기에 멋진 전문가 같기도 함.
  • 단, 회사나 업계에서 많이 사용하는 약어일 경우 !

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

  • easy to Search 검색하기 쉽고
  • easy to Mix 조합하기 쉽고
  • easy to Agree 수긍하기 쉽고
  • easy to Remember 기억하기 쉽고
  • easy to Type 입력하기 쉽고

• 이름을 잘 지으면 주석을 줄일 수 있음

  • 이름이 주석이 할 일을 대신하기 때문 !
  • 그러나 개발자마다 영어 실력에 차이가 있기 때문에 누구에게는 어려운 단어일 수도 있으니, 어쩔 수 없이 주석을 달아야 하는 경우도 있긴 함.

사용자와 소통하는 에러 메시지 쓰기

• 에러 메시지를 쓰기 전에 에러부터 없애자 ........ ^_ㅠ

  • 사용자가 보는 화면은 보통 UI/UX 디자이너 혹은 기획자가 만든 것이므로 서비스를 이용하며 개발자의 산출물 그 자체를 볼 수는 없다.

  • 그러나 사용자가 개발자의 산출물을 적나라하게 볼 때가 있는데, 바로 에러 메시지 가 뜰 때임.

    • 예를 들어, 사용자가 URL을 잘못 입력했거나, 사용자가 링크를 클릭했으나 해당 페이지가 없는 경우에만 404 에러가 뜨게 된다. 근데 이 404 에러가 후자의 경우에서 발생했다면 개발자들이 깨진 링크를 놔둬서 생긴 문제이므로 문제가 된다.
    • 깨진 링크를 고치지 않은 것은 개발자가 자기 소임을 다 하지 못한 것임.
    • 암튼 ! 개발의 초기단계부터 개발자용 에러 메시지 와 사용자용 에러 메시지 를 분리하여 작성하는 것이 좋다.

  • 그렇다면, 사용자용 에러 메시지란 ? )

    • 단순히 에러만 띄워주기 보단, '휴대폰 번호를 잘못 입력하셔서 회원가입을 진행할 수 없습니다. 휴대폰 번호 입력란에는 숫자만 입력하십시오' 와 같이 해당 오류의 원인과 해결 방법을 포함해주어야 한다.

독자 관점에서 릴리스 문서와 장애 보고서 쓰기

• '체인지 로그'는 개발자가 변경한 내용을 적은 것임.

• 그러나, 해당 체인지 로그를 보는 독자는 '새로운 것, 바뀐 것, 그래서 자기에게 좋거나 유익하거나 어떤 행동을 해야 할 지 명확하게 지시하는 것' 을 보고 싶어 함.

  • 따라서, 외부 개발자나 일반 사용자가 보는 체인지 로그를 쓸 때는 개발자 관점이 아니라 고객 관점에서 써야 한다.

    • 고객의 문제 해결을 앞쪽으로 옮기고, 개발자의 문제는 짧게 줄인다. 그 후 개조식으로 변경하면 됨 !

• if) 고객이 요구하거나 불평한 것이 이번 릴리스에 다 반영되지 않으면 고객은 다음 릴리스를 기다릴 수 밖에 없음. 그러나, 개발자가 언제 해결할지 약속하지 않는다면 ?

  • 그래서 다소 귀찮지만 다음 릴리스 항목으로 검토하는 것이 있다면 중요한 것은 공개하는 것이 좋음.

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

• 개발자가 기술 블로그를 잘 못 쓰는 이유 중 하나는 블로그에 글을 쓰는 방법이 학생이었을 때 배운 글쓰기 방법과 다르기 때문임.

• 우리가 학생이었을 때 주로 논설문, 설명문 쓰는 방법을 배웠는데 딱히 주장할 것이 없는 기술 블로그에서는 글 쓰는 데에 별 도움이 되지 않음.

  1. 주제 의식을 버리고 소재 의식으로 쓰자
  - 민족이나 권선징악, 자존감이나 자본주의 같은 추상적 가치인 주제의식을 기반으로 하기보다는, 특정한 대상이나 상황에 대한 자기만의 관점, 해결 방안을 뜻하는 소재 의식을 갖고 쓰는 것이 소재 우선 글쓰기임.

  • ex) 우아한 형제들 기술 블로그에 올라온 글 중 "데이터베이스의 자동증가 값을 기본키로 사용할 수 없을 때는 ?" -> 해당 글은 DB의 자동증가 값을 기본키로 사용할 수 없는 상황이 벌어졌고, 그 상황을 '어떠한 방법으로 해결한 내용' 임.

  2. 독자 수준이 아니라 자기 수준으로 쓰자

  • 보통 어떤 것을 쉽게 설명할 때 '비유법'을 사용함.
  • 그러나 비유법에는 한계가 분명히 있음. 단지 어떤 것의 원리를 '간접적'으로 이해한 것에 불과하기 때문.
  • 그렇기 때문에 개발자가 기술 블로그를 쓸 때는 독자를 생각해서 어려운 용어를 일부러 해석해서 풀어쓰거나, 쉬운 용어로 바꿀 필요가 없다.
    그냥 원래 사용하는 용어로 표기하되, 해당 용어를 정의한 위키피디아 링크나 사이트를 링크로 걸어두는 정도로도 충분하다.

  3. 재미있게 글을 쓰자

  • 정말 유머러스 보다는, 글쓰기에 기교가 있으면 독자들을 더 사로잡을 수 있음.
  • 좋은 기술 블로그는 개발자의 경험에서 우러나오는 내용을 적절한 글쓰기 기교로 녹여내어, 독자가 온몸으로 그 경험을 공감하고 끄덕이게 만들어야 한다.

• 기업의 기술 블로그 운영 팁

  • 기술 블로그는 회사의 가치를 높인다.

  • 채용 직무에 적합하면서 개발 능력이 우수한 개발자 채용에 도움이 된다.

    • 블로그가 활성화되면 자연스레 개발자들이 그 기업에 관심을 가지게 되고, 해당 회사가 구체적으로 어떤 개발을 하고 어떤 식으로 개발하고 어떤 문화를 가졌는지 파악하기 쉽기 때문.

  • 개발 과정에서 생긴 노하우를 체계적으로 축적할 수 있다.

    • 스타트업은 사내 문서 관리 체계가 미흡할 수 밖에 없기 때문.

  • 개발자가 스스로 공부하게 만든다.

    • 글을 써서 올리려면 지식을 체계화하는 과정이 필요하므로, 그 과정에서 개발자는 모르는 것을 찾아내서 알아내고 아는 것도 재확인하게 됨. 따라서 회사의 개발 수준을 높여서 개발자의 생산성도 향상되고, 개발자 스스로도 자신의 몸값을 높일 기회가 됨.