책 리뷰

[개발자의 글쓰기] 2장. 개발 시간을 줄여주는 이름짓기와 주석쓰기

Space Panda 2021. 2. 22. 17:05

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

    1. 개발자의 가장 큰 고민은 이름 짓기

      • 이름 짓기가 어렵긴 하지만 잘만 하면 코드를 짜기도 쉽고 이해하기도 쉽다.
      • 다른 개발자가 봤을 때 한 번에 무슨 뜻인지, 무슨 기능을 하는지 알아낼 수 있는 이름이어야 한다.

    2. 이름 짓기는 창조가 아니라 조합

    3. 코드의 네이밍 컨벤션은 영어 표기법을 상속받았다

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

      • 파스칼 표기법은 모든 단어에서 첫 글자를 대문자로 쓰는 방식이다.
      • 주로 클래스 이름에 사용한다.
      • 예 : class Object, class View, class TextView

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

      • 카멜 표기법은 첫 단어를 빼고 나머지 단어의 첫번째 글자만 대문자로 쓴다.
      • 주로 함수나 변수에 사용한다.
      • 예 : int totalCount=0; , void orderCoffee();

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

      • 변수와 구별하기 위해서 상수를 모두 대문자로 쓰고 언더스코어(_)로 단어를 연결한다.
      • 상수는 값이 변해서는 안된다는 점을 강조하고 주의시키기 위해 가독성을 높이는 방법으로 대분자를 선택한것이다.
      • 예: static final int COFFEE_MAX = 10;

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

      • 패키지와 모듈은 클래스나 함수보다 높은 위치이지만, 단순히 클래스와 함수를 담은 통에 불과하기 때문에 소문자로 쓴다.
      • 실용적인 이유가 있는데, 클래스 이름과 패키지 이름을 혼동할 수 있기 때문에 소문자를 써서 패키지와 모듈을 나타낸다.
      • 예 : kr.co.wikibook.android.developerwriting , import developerwriting

    8. BEM표기법

      • BEM(Block, Element, Modifier) 표기법은 '대상_요소-상태'를 위미한다.
      • 대상의 요소나 부분을 의미할 때는 언더스코어 두개(__)로 연결한다.
      • 대상이나 요소의 상태나 속성을 의미할 때는 하이픈 두 개(--)로 연결한다.
      • 예: .form{}, .form__button{}, .form__button--disabled{}

    9. 가독성과 소통이 먼저다

      • 중요한것은 표기법 자체가 아니라 가독성과 소통이다.
      • 하지만 가독성이 높다고 소통이 더 잘되는것은 아니다. 소통을 위해서는 서로가 같은 컨벤션을 지켜야 한다.
      • 하나의 프로그램과 관련된 개발자들끼리는 코딩하기 전에 기본적인 컨벤션 규칙을 정하는게 기본이다.

  1. 변수 이름을 잘 짓는 법

    1. i는 변수 이름이지만 d는 아니다

      • i는 관습적으로 integer와 index의 첫글자로 간주되므로 개발자가 반복문의 카운터나 배열 인덱스로 사용해도 문제가 없다.
      • a나 d 처럼 아무런 의미가 없는 글자를 변수로 쓰는것은 좋지않다.

    2. 긴 이름? 짧은 이름? 검색 잘 되는 이름!

      • 개발환경이 많이 좋아졌기 때문에 변수의 길이를 짧게 해야될 이유는 없어졌다. (헝가리안 표기법은 legacy가 되었다 해도 무방)
      • 검색이 잘되는 이름으로 지어라.

    3. 복수형을 나타내는 s를 붙일까 말까?

      • 배열(array)를 복수(-s)로 나타내는 방법이 있다.
      • 변수명은 복수형(-s)이더라도 함수에서는 'array'를 사용하는 편이 나을 수도 있다.
      • 어떤것이 편할지는 개인마다 다르겠지만 회사 또는 프로젝트 안에서는 규칙을 하나로 통일 하도록 한다.
      • 예 : checkUserNamesUnder2Characters() , checkUserNameArrayUnder2Characters()

    4. 약어를 쓰는 것이 좋을까? 안 쓰는 것이 좋을까?

      • 개발자에 따라 약어에 대한 의견이 엇갓린다.
      • 필자는 서비스 이름이나 패키지 이름, 또는 클래스 이름에 약어를 쓰는것도 나쁘지 않다고 생각한다.
      • 회사나 업계에서 많이 사용하는 약어라면 코드에 사용하는 것이 좋다.

    5. 중요한 단어를 앞에 쓴다

      • 예 : int visitorTotal, int buyerTotal, int windowSizeMax, int vipCount

    6. 함수 이름 짓는 순서

      1. 함수 문장을 영어로 바꾸자
        • 사용자 이름을 input 태그에서 가져온다 -> get user's name from the text input field
      2. 정관사나 불필요한 단어를 빼고 of는 앞뒤 단어를 바꾼다. 소유격도 없애자
        • get user name from input field
      3. 띄어쓰기를 없애고 두번째 단어부터는 첫 글자를 대문자로 바꾸자.
        • getUserNameFromInputField()
      4. 함수 사용시 의미상 없어도 되는 단어를 제거한다.
        • getUserNameFromField()

  1. 좋은 이름의 기준, SMART

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

      • p.66참고

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

      • p.68참고

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

      • p.70 참고

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

      • p.72 참고

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

      • p.74 참고

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

    1. 이름을 잘 지으면 주석을 줄일 수 있다

      • 이름을 잘 지으면 주석을 대폭 줄일 수 있다. 이름이 주석이 할일을 대신하기 때문이다.

    2. 처음부터 주석 없이 코딩하는 연습을 하자

    3. 주석이 필요한 때도 많다

      • 코드의 정확성을 높이고 버그를 줄이는 계기가 된다면 주석을 써주는 것이 좋다(복잡한 알고리즘 풀이 등등)

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

    1. 코드는 의미를, 주석은 의도를

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

    2. 주석의 반복

      • 같은 주석이 여러번 나오면 코드를 파악하는데 장애가 된다.
      • 하지만 코드를 처음부터 읽지 않고, 필요한 부분을 찾아보는 개발 가이드 문서의 경우는 주석이 반복이 도움이 될 수 있다.

    3. 주석의 발췌와 요약

      • 발췌는 중요한 것을 뽑아내는 것이다. 중요한 것을 뽑으려면 덜 중요한 것을 빼야 한다.

    4. 주석도 코드다

      • 비슷한 코드와 주석을 반복하다 보면 복사해서 붙여넣은 뒤 수정하는 과정에서 종종 실수가 발생한다(잘못된 주석을 넣을때가 있다)
      • 잘못된 주석이 많아지면 오히려 코드를 이해하는데에 장애가 된다.
      • 주석도 코드의 일종이라고 생각하고 주석 리뷰도 꼼꼼히 해야한다.