솜이의 데브로그

2장 ) 이름 짓기와 주석 쓰기 본문

책을 읽자/개발자의 글쓰기

2장 ) 이름 짓기와 주석 쓰기

somsoming 2021. 10. 12. 23:05

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

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

함수가 어떤 일을 하는지 이름만 보고도 짐작하게 만들어야한다.

즉, 다른 개발자가 봤을 때 한 번에 무슨 뜻인지, 무슨 기능을 하는지 알아낼 수 있는 이름이어야한다. 그러면서도 아주 간결해야 한다.

 

네이밍 규칙들

  • 자바 네이밍 컨벤션을 철저히 준수한다.
    • 클래스는 UpperCamelCase
    • 함수와 변수는 lowerCamelCase
    • 상수는 UPPER_DELIMITER_CASE
  • 네이밍은 보통 16글자, 3단어를 조합한다.
    • 클래스 네임 : 3.18단어
    • 함수 네임 : 3.36 단어
    • 변수 네임 : 2.57 단어
  • 품사는 주로 명사, 동사, 형용사의 조합이다.
    • 명사 + 명사 + 명사
    • 동사 + 명사 + 명사
    • 형용사 + 명사 + 명사 등

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

  • 네이밍 컨벤션은 기본적으로 영어의 표기법을 준수한다.
  • 영어의 대문자 표기 원칙의 몇 가지 특성
    • 중요하거나 크거나 특정한 것을 가리키거나 제목에 해당하는 명사는 모두 첫 글자를 대문자로 쓴다.
    • 그런 명사들이 이어질 때는 첫 글자를 모두 대문자로 쓴다.
    • 명사나 관사가 아닌 동사, 형용사 등은 소문자를 쓴다.

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

  • 모든 단어에서 첫 글자를 대문자로 쓰는 방식.
  • 주로 클래스 이름에 사용. 단어의 첫 글자를 모두 대문자로 쓴다.

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

  • 첫 단어를 빼고 나머지 단어의 첫 번째 글자만 대문자로 쓴다.
  • 주로 함수나 변수에 사용. 첫 단어의 첫 글자를 소문자로 쓴다.

프로그래밍 할 때는 소문자를 쓰는 변수와 구별하기 위해 상수를 모두 대문자로 쓰고 언더스코어(_)로 단어를 연결한다.

 

 

2. 변수 이름을 잘 짓는 법

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

  • i는 정수를 뜻하는 integer와 지수를 뜻하는 index의 첫 글자로 간주.
  • d는 아무런 의미 없는 글자이므로 변수로 쓰지 않는 것이 좋다.

 

3. 좋은 이름의 기준, SMART

패키지, 클래스, 모듈, 함수, 변수 등의 이름을 정할때 좋은 이름인지 확인하는 기준 5가지

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

 

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

  • 고전적 범주화를 이요해 한 단계 상위 범주의 이름을 태그처럼 덧붙인다.
  • 고전적 범주화 : 특정한 대상들을 묶어 상위 범주를 만들어 이해하는 것.ERROR_SERVER_TIMEOUT ERROR_NO_RESULT ERROR_BAD_REQUEST ERROR_SERVER_ALLOWED_REQUESTS_EXCESS
  • ex)

특정 변수나 함수를 검색할 일이 정말 많은지, 검색하더라도 바로 찾고 이해할 수 있는지, 회사의 네이밍 컨벤션에 위배되지 않는지 등을 먼저 따져 본 뒤 사용하자.

 

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

  • 개발 언어의 문법과 조합해 이름을 짓는 것이 좋다.

 

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

  • 수긍할 수 있는 이름이란 누가 보더라도 그렇게 짓는 것이 더 낫다고 동의하는 이름이다.

 

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

  • 약자를 쓸 때 시청각적으로 완결시키면 더 잘 기억하게 된다.
  • 또는 연상어를 떠올려 기억하기 쉽게 짓는다.

 

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

  • 오타를 낼 가능성이 작은지, 입력하기 쉬운지, 다른 사람에게 말로 전달하기 쉬운지 등을 검토.

 

 

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

  • 이름을 잘 지으면 주석을 줄일 수 있다.
  • 처음부터 주석 없이 코딩하는 연습을 하자. ex) JSON
  • 영어로 애매한 경우 (이하,미만)에는 주석을 다는게 좋다.

 

 

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

  • 개발자가 어떤 의도를 전달하는 이유는 다른 개발자를 위한 것이다.
  • 코드를 왜 이렇게 작성했는지 설명 등을 주석에.
  • 개발자 가이드 문서등의 경우 특정 함수만을 검색하는 경우가 있으므로 같은 주석을 반복해서 써야 함.
  • 잘못 쓴 코드는 디버깅으로 바로잡을 수 있지만, 잘못 쓴 주석은 개발자가 신경쓰지 않으면 바로잡을 수 없다.
  • 주석도 코드라고 생각 → 코드리뷰를 하면서 주석 리뷰도 꼼꼼히하는 것이 좋다.

 

 

느낀점

인공지능과 맞춤법 검사기를 활용해 주석으로 자동으로 디버깅하는 기술 너무 좋은 아이디어같다.

누군가가 개발중이겠지? 빨리 나왔으면ㅎ

협업할 땐 설명이 많이 필요하니까 주석 다는게 습관이었는데 나중에 정리하다 놓치는 부분이 많은 것 같아서 처음부터 주석을 깔끔하게 다는 습관을 가져야겠다.