개발자의 글쓰기 2장 정리

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

📎 네이밍 컨벤션, 이유를 알고 쓰자

• 코드를 짜기도 쉽고 이해하기도 쉽다.
• 문서 대신에 코드로 소통하려면 좋은 이름 짓기는 필수
• 이름 짓기는 창조 과정이 아니라 정해진 원칙으로 적절한 단어를 선택해 조합하는 과정
• 컨벤션을 만든 이유는 가독성과 소통 때문이다. 코드를 읽기 쉽게 만들고 다른 개발자와 소통하기 위해서

📎 변수 이름을 잘 짓는 법

• 회사나 업계에서 많이 사용하는 약어라면 코드에 사용하는 것이 좋다.
• 약어를 만드는 좋은 방법은 보편성을 기준으로 정하는 것이다.
• 중요한 단어를 앞에 와야한다.
• 함수는 시스템이 할 일을 나타내는 것이지 사용자가 할 일을 나타내는 것이 아니다.

📎 좋은 이름의 기준, SMART

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

easy to Search 검색하기 쉽게 이름 짓는 법

• 고전적 범주화를 이용해 한 단계 상위 범주의 이름을 태그처럼 덧붙이면 됨.
  • 고전적 범주화 : 특정한 대상들을 묶어 상위 범주를 만들어 이해하는 것
• 같은 접두어를 가진 함수나 변수의 개수가 너무 많으면 안 붙이는 것만 못하다. 체계 먼저 다듬어야 한다.
• 접두어를 붙이기 전에 특정 변수나 함수를 검색할 일이 정말 많은지, 검색하더라도 바로 찾고 이해할 수 있는지, 회사의 네이밍 컨벤션에 위배되지 않는지 따져 본 뒤 사용하자.

easy to Mix 조합하기 쉽게 이름 짓는 법

• 속성 대신 개념으로 이름을 짓는다.
• 개발 언어의 문법과 조합해 이름을 짓는다.

easy to Agree 수긍하기 쉽게 이름 짓는 법

• 누가 보더라도 그렇게 짓는 것이 더 낫다고 동의하는 이름
• 그 상황에서 그런 이름을 쓰는 것이 마땅하다고 생각할 수 있어야 하는 것
• 이름은 대상을 구별하기 위한 것이다. 구별할 필요가 없는 것에까지 이름을 새로 지을 필요는 없다.

easy to Remember 기억하기 쉽게 이름 짓는 법

• 개발자만 보는 개발 관련 문서라면 보편적으로 쓰는 이름은 그대로 써도 무방하다. 이미 널리 알려진 용어는 그냥 쓰는 것이 효율적.

easy to Type 입력하기 쉽게 이름 짓는 법

아마 오탈자로 가장 유명하나 것은 HTTP Referer일 것이다. 원래 Referrer인데 RFC 문서에서 r을 하나 빼먹어서 쓰는 바람에 이후에 모두 Referer로 쓴다. ㅋㅋㅋ

• 자주 사용되거나 중요한 이름이라면 입력하기 쉬운지, 오타를 낼 가능성이 작은지, 다른 사람에게 말로 전달하기 쉬운지 검토해 보는 것이 좋다.

📎 좋은 코드에는 주석이 없다?

• 이름을 잘 지으면 주석을 대폭 줄일 수 있다. 이름이 주석이 할 일을 대신하기 때문.
• 주석이 언어의 문법까지 일일이 설명할 필요는 없다.
• 적절한 때에 주석을 사용하자.

📎 다른 개발자를 배려하는 주석 쓰기

• 이름이 개발자의 의도를 모두 전달할 수는 없다. 의도를 이름에 모두 포함하면 코드가 지저분해지고 가독성이 현저히 떨어진다.
• 주석이 언제 어떻게 읽히는지에 따라 반복해서 쓸 것인지를 결정해야 함. 무조건 처음 한 번만 쓰고 같은 내용이 반복되는 주석을 지워야만 좋은 것은 아님.
• 주석의 악순환에서 벗어나는 가장 좋은 방법은 주석도 코드라고 생각하는 것이다.
  • 코드 리뷰를 하면서 주석 리뷰도 꼼꼼히 해야 한다.
  • 불필요한 주석은 없애고, 꼭 필요한 주석은 반드시 코드처럼 다뤄야 한다.