1. 도입
코드 문서화를 왜 하는가?
•
클린 코드에서 작명과 주석의 중요성에 대해 강조하는 이유는 무엇일까?
•
커밋 메시지를 제대로 달면 어떤 점이 좋을까?
•
오류 메시지와 오류 코드 역시 코드 문서화의 종류가 아닐까?
2. 프로그래밍 과정에서 이름 짓기와 관련된 심리학
오해할 수 없는 이름의 중요성
•
코드 기반에서 식별자 이름이 중요하다.
◦
타입, 변수, 메소드, 함수, 모듈, 라이브러리, 네임스페이스 등
◦
코드 기반의 상당 부분을 차지
◦
코드 리뷰 시 지적되는 사항
◦
이름은 문서화의 가장 쉬운 형태
◦
이름이 표식 역할을 함
•
좋은 이름과 나쁜 이름은 어떻게 구분할까?
◦
문법적인 정의
▪
비정상적인 대문자 사용: paGecoUnter
▪
연속된 밑줄 두 개: page__counter
▪
사전 미등재 단어: page_countr
▪
너무 많은 단어: page_counter_converted_andnormalized_value
▪
짧은 이름: P
▪
열거형 식별자에서 임의의 선언 순서: CardValue={ACE,EIGHT,FIVE,FOUR,JACK,KING…}
▪
식별자 인코딩: int_page_counter
▪
명명법 규약 이상: Page_Counter
◦
코드 기반 내에서 일관성
▪
프로그램 개발 초기에 만들어진 식별자의 품질이 계속 유지된다.
•
변수명이 가지고 있는 정보가 너무 많다.
◦
코드 도메인에 대한 정보
◦
프로그래밍 자체에 대한 정보
◦
변수에 담긴 이미 알고 있는 정보
더 나은 이름을 위한 모델
•
페이텔슨의 3단계 모델
1.
이름에 포함할 개념을 선택한다.
•
업무 영역 또는 컴퓨터 기술 별로 고민한다. 이름의 의도가 중요하다. 개체가 어떤 정보를 보유하며 무엇을 위해 사용되는가?
•
정보를 제공해야하는 경우도 있다. 단위, 안전한 데이터인가? 등
2.
각 개념을 나타낼 단어를 선택한다.
•
업무 영역에서 사용되는 특정 단어나 코드 기반 전체에서 사용되는 단어
•
동의어나 유의어 등 경쟁적인 옵션이 있을 경우 문제가 있을 수 있다.
•
어휘 사전을 따로 정의해두어야 할지도 모른다.
3.
이 단어를 사용해 이름을 구성한다.
•
선택된 단어를 사용해 이름을 구성할 때, 자연어에 맞출 필요가 있다.
◦
pointMax vs maxPoint
◦
indexOf, elementAt
간단 정리
•
프로그래밍 과정에서 이름이 끼치는 영향은 매우 높다.
◦
좋은 이름과 나쁜 이름의 차이를 인식해야 한다.
◦
오해할 수 없는 이름을 피하기 위해 쉬운 이름을 어떻게 만들어낼지 고민해야 한다.
•
더 나은 이름을 위해 페이텔슨의 3단계 모델을 기억하라.
◦
이름에 포함할 개념을 선택한다.
◦
각 개념을 나타낼 단어를 선택한다.
◦
단어들을 사용해 이름을 구성한다.
3. 프로그램 개발 과정에서 영어로 이름 짓기
기본 원칙
•
서술적인 이름을 사용하라
•
적절한 추상화 수준에서 이름을 선택한다.
◦
상세한 구현을 드러내는 이름을 피하자.
◦
작업 대상 클래스나 함수가 위치하는 추상화 수준의 이름을 선택하자.
•
가능하다면 표준 명명법을 활용하라.
◦
프로젝트에 유효한 의미가 담긴 이름을 많이 사용할수록 독자가 코드를 이해하기 쉬워진다.
▪
ex) Decorator, toString, Impl
•
명확한 이름
•
넓은 영역에 사용되는 변수에는 긴 이름을 사용하자.
•
인코딩을 피하라
◦
이름에 유형 정보와 범위 정보를 넣어서는 안 된다.
•
이름으로 부수 효과를 설명하라.
작명 규칙
•
이름에 정보를 담자
◦
단어를 잘 선택해야 한다. 의미를 활용해서커버 추가
◦
보편적인 이름 피하기
◦
추상적인 이름 대신 구체적인 이름 활용
◦
추가적인 정보 덧붙이기
▪
평문 암호인 경우, password → plaintext_password
◦
눈에 잘 띄게 만들기
▪
네이밍 컨벤션
•
클래스 이름은 도메인의 문제를 구체적으로 나타내는 명사구가 적합하다.
•
메서드 이름은 동사나 동사구가 적합하다.
•
한 개념에 한 단어만 사용하라.
•
한 단어를 두 가지 목적으로 사용하지 마라.
◦
추상적인 단어인 add나 get같은 단어를 피하라.
•
length vs count vs size
◦
연속적인 구성 요소 ⇒ length
◦
더 느슨한 구성 요소의 숫자를 지정 ⇒ count
◦
구성 요소의 최대 크기를 지칭 ⇒ size
◦
할당된 메모리를 지칭 ⇒ capacity
간단 정리
•
앞서 설명한 심리학을 응용해 영어로 이름 짓는 몇 가지 기본 원칙이 존재한다.
◦
핵심은 추상화와 구체화 사이의 밸런스다.
•
구체적인 작명 규칙은 기존 코드 기반이나 오픈 소스 코드를 많이 읽어보면 도움이 된다.
◦
주요한 부분은 이름에 맥락과 정보를 얼마나 잘 담느냐에 달려 있다.
4. 영어로 주석 제대로 달기
코드 주석
•
코드 주석의 목적
◦
코드를 읽는 사람이 코드를 작성한 사람만큼 코드를 잘 이해하기 위해 돕는다.
◦
코딩을 수행하면서 머리 속에 들어있는 정보를 정리한다.
•
주의할 점
◦
나쁜 코드에 주석을 달지 말고 새로 짜라.
◦
주석은 오래될 수록 코드에서 멀어진다.
•
설명하지 말아야할 내용은?
◦
코드만 봐도 충분히 알 수 있는 내용을 다시 설명하는 주석
◦
나쁜 함수나 변수명을 설명하려 드는 내용
•
설명하면 좋은 내용
◦
코드가 특정 방식을 선택한 이유
◦
코드에 담긴 결함이나 향후 할 일
◦
어떤 상수가 특정 값으로 정해진 이유
◦
평범한 사람이 예상치 못한 특이한 동작
◦
파일/클래스 수준에서 큰 그림을 설명하는 주석
코드 문서화
•
Javadocs와 같은 코드 문서화 도구에서 주의할 사항
◦
형태가 갖춰져 있으므로 중복되거나 그릇된 정보를 제공할 가능성이 있다.
◦
공개 API에 대해서만 작성하기 때문에 시스템 내부의 클래스와 함수를 작성해서는 안 된다.
•
주석과 관련된 스타일 가이드
◦
2인칭이 아닌 3인칭을 사용하라.
◦
메소드 설명은 동사구로 시작하라.
◦
클래스/인터페이스/필드는 주어를 생략하라.
간단 정리
•
코드 주석은 코드의 How를 설명하는 대신 핵심 요약이나 왜, 배경 맥락을 설명해야 한다.
•
코드 문서화는 내부 동작 방식이 아니라 파일이나 클래스 수준 주석에서 큰 그림을 설명한다.
5. 영어로 커밋 메시지 제대로 만들기
•
커밋 메시지가 중요한 이유는 무엇을 왜 어떻게 변경했는지 이해하는 과정에 있어서 단초를 제공한다.
커밋 메시지 기초
•
커밋은 작고 한 번에 문제 하나만 다루는 편이 좋다.
◦
HOW 대신 WHAT과 WHY
◦
제목과 본문으로 구성하라.
◦
짧게 쓰는 것이 좋다.
◦
Jira 티켓, 패턴 페이지, 메뉴얼 페이지 등 참고 링크가 있으면 좋음
•
커밋 메시지에서 우리가 고민해야 할 사항
◦
이 변경이 필요한 이유는?
◦
이 문제를 해소하는 방법은?
◦
변경이 가져온 부작용은?
좋은 커밋 메시지를 위한 영단어 목록
•
FIX: 올바르지 않은 동작을 고친 경우
•
ADD: 코드나 테스트, 예제, 문서를 추가한 경우
•
REMOVE: 코드 삭제가 있을 경우
•
USE: 뭔가를 사용해 구현을 하는 경우
•
REFACTOR: 리팩토링을 하는 경우
•
SIMPLIFY: 코드를 단순화하는 경우
•
UPDATE: 수정/추가/보완하는 경우
•
IMPROVE: 호환성/테스트 커버리지/성능/접근성 등 향상이 있을 경우
•
IMPLEMENT: 모듈이나 클래스 단위로 코드를 추가한 경우
•
MOVE: 코드 이동이 있는 경우
간단 정리
•
커밋 메시지는 형상 관리 이력에서 가장 중요한 요소다.
◦
변경이 필요한 이유, 문제를 해결하는 방법, 변경이 가져오는 부작용 등을 담고 있어야 한다.
•
커밋 메시지를 제대로 작성하기 위한 원칙
◦
주제와 본 내용 사이에 한 줄을 띄워라
◦
주제 행은 일반적으로 50 글자 내외가 좋다
◦
주제 행 첫 글자는 대문자가 되어야 한다
◦
주제에 점을 찍지 마라
◦
주제 행을 명령문으로 만들어라
◦
본문은 72행에서 행갈이를 하라
◦
방법이 아니라 이유를 설명하라
6. 영어로 오류 메시지 제대로 만들기
오류 메시지 작성이 어려운 이유
•
오류는 보통 추상적으로 작성되기 마련이기 때문에 이해하기 쉽게 작성하는 것이 어렵다.
•
좋은 오류 메시지의 세 가지 구성 요소
◦
맥락: 오류의 원인은? 실패했을 때 코드가 무엇을 하고 있었는지
▪
오류 메시지는 이야기다. 오류 메시지의 경우 문제를 일으킨 코드가 실패하는 경우, 수행하려는 작업을 독자에게 설명하라.
⇒ Couldn’t parse Config file ⇒ Couldn’t parse config file: /etc/sample-config.properties
▪
파일과 관련된 경우에는 절대 경로를 출력하는 것이 좋다. 만약 파일의 특정 부분인 경우, 줄 번호나 줄 자체를 출력하는 것이 좋다.
◦
오류 자체: 정확히 무엇이 실패했는지
▪
메시지는 짧고 간결하게 적는 것이 좋다.
•
문제의 심각성, 발생한 문제 소개, 문제가 발생한 위치, 문제가 발생한 이유를 포함해야 한다.
◦
오류 완화 방법: 오류를 극복하기 위해 어떤 일을 해야 하는지
▪
사용자가 오류를 완화하기 위한 조치를 설명해야 한다.
▪
회피하기 위해 취해야할 조치를 설명하며 오류 코드를 포함하면 더욱 좋다.
주의 사항
•
오류 메시지를 읽는 독자는?
◦
일반 사용자: 최종 소프트웨어를 사용하는 입장에서 오류를 바라본다.
◦
개발자/운영자: 라이브러리 혹은 프레임워크는 사용하는 입장에서 오류를 바라본다.
•
주의
◦
일반 사용자를 대상으로 제공하는 오류 메시지의 경우, 민감한 보안 관련 내요은 노출해서는 안 된다.
간단 정리
•
좋은 오류 메시지의 세 가지 구성 요소
◦
맥락, 오류 자체, 오류 완화 방법
•
짧으면서도 할 이야기는 다 하는 정확한 메시지가 중요하다.
