Skip to content

item-51.md

Latest commit

 

History

History
291 lines (216 loc) · 12.6 KB

item-51.md

File metadata and controls

291 lines (216 loc) · 12.6 KB

item 51 : 메서드 시그니처를 신중히 설계하라

1. 개별 아이템으로 두기 애매한 API 설계 요령

1) 메서드 이름을 신중히 짓자.

변수명 지어주는 사이트 : https://www.curioustore.com/#!/

항상 표준 명명 규칙을 따라야 한다.

자바 표준 명명 규칙

  1. 클래스와 인터페이스 (Class & Interface):
    • 대문자로 시작하며 각 단어의 첫 글자를 대문자로 표기한다 (PascalCase).
    • 클래스 이름은 보통 명사 또는 명사구로 표현한다.
    • 예: Person, DataManager, HttpRequestHandler.
  2. 메서드 (Method):
    • 소문자로 시작하며 각 단어의 첫 글자는 대문자로 표기한다 (camelCase).
    • 메서드 이름은 동사 또는 동사구로 작성하여, 메서드가 수행하는 동작을 명확히 설명해야 한다.
    • 예: calculateTotal(), fetchUserData(), isUserLoggedIn().
  3. 변수 (Variable):
    • 소문자로 시작하며 각 단어의 첫 글자는 대문자로 표기한다 (camelCase).
    • 변수 이름은 가능한 구체적이고 명확하게, 변수의 목적을 설명하도록 작성한다.
    • 예: userName, accountBalance, maxRetryCount.
  4. 상수 (Constant):
    • 모든 글자를 대문자로 표기하며 단어 간에 밑줄 (_)을 사용한다 (SNAKE_CASE).
    • 예: MAX_BUFFER_SIZE, DEFAULT_TIMEOUT.
  5. 패키지 (Package):
    • 모두 소문자로 표기하며 회사 도메인을 뒤집은 형태로 시작한다.
    • 예: com.example.app, org.openai.utils.

메서드 이름의 예시와 부가설명

  1. 동사 또는 동사구로 명확히 표현:
    • 예: save(), load(), calculateInterest().
    • 이처럼 메서드 이름은 그 메서드가 무슨 작업을 하는지 명확하게 나타내야 함
  2. 부울 값을 반환하는 메서드는 is로 시작:
    • 예: isValid(), isEmpty(), isUserActive().
    • 부울 값을 반환하는 메서드의 경우 is를 접두사로 붙이는 것이 일반적
  3. 설명적인 이름으로 의미 명확히 하기:
    • 예: getCustomerData(), sendEmailNotification().
    • 긴 이름을 피해야 하지만, 너무 짧고 애매한 이름도 피해야 합니다. 적절하게 설명적이면서 이해할 수 있는 이름을 사용하는 것이 중요
  4. 자바 라이브러리의 명명 규칙과 일관성 유지:
    • 예: 자바의 컬렉션 메서드들은 add(), remove(), clear(), contains()와 같은 이름을 사용한다.
    • 이처럼 널리 사용되는 메서드 이름을 참조함으로써 일관성을 유지하고 다른 개발자들이 쉽게 이해할 수 있게 된다.

명명 규칙 예시

  • 좋은 예시:

    public void sendEmailNotification(String email) {
    // 이메일 알림을 보낸다.
}

public boolean isAccountActive() {
    // 계정이 활성화되어 있는지 여부를 반환한다.
}

public double calculateTotalPrice(List<Item> items) {
    // 아이템의 총 가격을 계산한다.
}

  • 나쁜 예시:

    public void sE(String e) {
    // 너무 짧고 모호하다. 메서드가 무슨 일을 하는지 전혀 알 수 없다.
}

public void performAction() {
    // 메서드가 어떤 동작을 수행하는지 알 수 없다. 메서드 이름이 너무 일반적이다.
}

public boolean accountStatus() {
    // 부울 값을 반환하지만, `is` 접두사가 없어 의미가 명확하지 않다.
}

요약

  • 명확하고 일관성 있게 메서드 이름을 짓는 것이 중요하다. 이해할 수 있고, 같은 패키지에 속한 다른 이름들과 일관되게 짓는 게 최우선 목표다.
  • 메서드 이름은 무엇을 하는지 쉽게 이해할 수 있도록 지어야 하며, 동사 형태로 시작하여 동작을 설명해야 합니다.
  • 긴 이름은 피하자.
  • 자바 표준 명명 규칙을 따르고, 필요시 자바 API 가이드를 참조하여 개발자 커뮤니티에서 널리 받아들여지는 방식으로 이름을 짓는 것이 좋다.

2) 메서드의 소임과 직교성 (Orthogonality)

편의 메서드를 너무 많이 만들지 말자.

  • 각 메서드는 자신의 역할에만 충실해야 한다: 많은 기능을 하나의 메서드에 넣으면 복잡해지고 이해하기 어려워지므로, 명확한 단일 책임 원칙을 지켜야 한다.
  • 메서드가 너무 많은 클래스와 인터페이스는 피해야 한다: 유지보수와 사용이 어렵기 때문에 필요한 최소한의 기능을 메서드로 정의해야 한다.
// 나쁜 예시 - 여러 기능을 하나의 메서드에 몰아넣음
public void manageOrderAndSendReceipt(Order order) {
    // 주문 관리
    processOrder(order);
    // 영수증 발송
    sendReceipt(order);
}

// 좋은 예시 - 메서드가 각각의 소임을 다함
public void processOrder(Order order) {
    // 주문 처리 로직
}

public void sendReceipt(Order order) {
    // 영수증 발송 로직
}

직교란 수학에서 온 용어로, 서로 직각（90。）을 이루며 교차 한다는 뜻이다. 수학의 관점에서 직교하는 요소들은 서로 독립적이다.

  • 직교성(Orthogonality): 기능 간 독립성을 높여 메서드 수를 줄이는 효과를 기대할 수 있다. 기능을 잘게 나누어 필요한 기본 기능들만 제공하면, 그 기능들을 조합하여 더 복잡한 동작을 구현할 수 있다. 예시로 List의 subList()와 indexOf() 메서드를 들 수 있다.
List<String> list = Arrays.asList("a", "b", "c", "d", "e");
List<String> subList = list.subList(1, 4);  // ["b", "c", "d"]
int index = subList.indexOf("c");           // 1

“직교성이 높다”라고 하면 “공통점이 없는 기능들이 잘 분리되어 있다” 혹은 “기능을 원자적으로 쪼개 제공한다” 정도로 해석할 수 있다. 예를 들어 본문의 List 설명에서 ‘부분리스트 얻기’와 ‘주어진 원소의 인덱스 구하기’는 서로 관련이 없다. 따라서 두 기능을 개별 메서드로 제공해야 직교성이 높다고 할 수 있다.

3) 매개변수 목록 유지

  • 매개변수는 4개 이하로 유지하는 것이 좋다. 매개변수가 많아지면 기억하기 어렵고 사용자가 혼동할 수 있다.
  • 같은 타입의 매개변수가 여러 개 연달아 나오는 경우는 특히 피해야 한다. 매개변수의 순서를 잘못 입력할 가능성이 있기 때문이다.
// 나쁜 예시 - 매개변수가 너무 많음
public void createUser(String firstName, String lastName, String email, String phoneNumber, String address, String city, String zipCode) {
    // 사용자 생성 로직
}

// 좋은 예시 - 매개변수 수를 줄이기 위해 도우미 클래스를 사용
public void createUser(UserInfo userInfo) {
    // 사용자 생성 로직
}

// 도우미 클래스
public class UserInfo {
    private String firstName;
    private String lastName;
    private String email;
    private String phoneNumber;
    private String address;
    private String city;
    private String zipCode;
    
    // 생성자, 게터, 세터 등을 정의
}

4) 매개변수 수 줄이는 세 가지 기술

  1. 메서드 나누기: 메서드를 여러 개로 쪼개 각각이 원래 매개변수 목록의 부분집합을 처리하도록 한다. 이렇게 하면 메서드 수는 늘어날 수 있지만 기능 간의 독립성을 높여 유지보수를 쉽게 한다. java.util. List 인터페이스가 좋은 예다.
// 나쁜 예시 - 모든 기능을 하나의 메서드로 처리
public void processPayment(String cardNumber, String expiryDate, double amount) {
    // 결제 처리 로직
}

// 좋은 예시 - 메서드를 나눠서 책임 분리
public void validateCard(String cardNumber, String expiryDate) {
    // 카드 유효성 검사
}

public void executePayment(double amount) {
    // 결제 실행
}
  1. 도우미 클래스 활용: 매개변수 여러 개를 묶어주는 도우미 클래스를 만들기. 일반적으로 이런 도우미 클래스는 정적 멤버 클래스로 둔다. 특히 잇따른 매개변수 몇 개를 독립된 하나의 개념으로 볼 수 있을 때 추천하는 기법이다. 예를 들어 카드의 숫자와 무늬를 묶어 하나의 매개변수로 만들면 API와 클래스 구현이 깔끔해진다.
// 도우미 클래스를 활용해 매개변수를 묶기
public class CardInfo {
    private String cardNumber;
    private String expiryDate;

    // 생성자와 게터를 정의
}

public void processPayment(CardInfo cardInfo, double amount) {
    // 결제 처리 로직
}
  1. 빌더 패턴 응용: 메서드 호출에서도 빌더 패턴을 응용하여 많은 매개변수를 처리한다. 먼저 모든 매개변수를 하나로 추상화한 객체를 정의하고, 클라이언트에서 이 객체의 세터(setter) 메서드를 호출해 필요한 값을 설정하게 하는 것이다.
  • 이때 각 세터 메서드는 매개변수 하나 혹은 서로 연관된 몇 개만 설정하게 한다.
  • 클라이언트는 먼저 필요한 매개변수를 다 설정한 다음, execute 메서드를 호출해 앞서 설정한 매 개변수들의 유효성을 검사한다. 마지막으로, 설정이 완료된 객체를 넘겨 원하 는 계산을 수행한다.
public class Payment {
    private String cardNumber;
    private String expiryDate;
    private double amount;

    public static class Builder {
        private String cardNumber;
        private String expiryDate;
        private double amount;

        public Builder cardNumber(String cardNumber) {
            this.cardNumber = cardNumber;
            return this;
        }

        public Builder expiryDate(String expiryDate) {
            this.expiryDate = expiryDate;
            return this;
        }

        public Builder amount(double amount) {
            this.amount = amount;
            return this;
        }

        public Payment build() {
            Payment payment = new Payment();
            payment.cardNumber = this.cardNumber;
            payment.expiryDate = this.expiryDate;
            payment.amount = this.amount;
            return payment;
        }
    }
}

// 사용 예시
Payment payment = new Payment.Builder()
                        .cardNumber("1234-5678-9012-3456")
                        .expiryDate("12/24")
                        .amount(100.0)
                        .build();

5) 매개변수 타입 선택

  • 클래스 대신 인터페이스 사용: 매개변수 타입으로 인터페이스를 사용하는 것이 클래스보다 유연하다. 예를 들어 Map 인터페이스를 사용하면 여러 구현체(HashMap, TreeMap 등)를 사용할 수 있다.
// 나쁜 예시 - 특정 구현체에 의존
public void processData(HashMap<String, String> data) {
    // 데이터 처리 로직
}

// 좋은 예시 - 인터페이스 사용
public void processData(Map<String, String> data) {
    // 데이터 처리 로직
}
  • boolean 대신 열거 타입 사용: 가능하면 boolean 대신 2개 이상의 값을 가지는 열거형(enum)을 사용합니다. 열거형은 코드의 의미를 명확히 전달할 수 있고, 선택지를 쉽게 확장할 수 있다.
public enum TemperatureScale { FAHRENHEIT, CELSIUS, KELVIN }

// 나쁜 예시
public Thermometer newInstance(boolean isCelsius) {
    // 섭씨 온도계를 반환
}

// 좋은 예시 - 열거형 사용
public Thermometer newInstance(TemperatureScale scale) {
    // 주어진 온도 단위에 맞는 온도계를 반환
}

6) API 설계 원칙

  • 편의성을 위한 고수준 기능 제공은 신중히: 자주 사용되는 조합이나 성능 최적화를 위한 고수준 기능을 별도로 제공할 수 있지만, 필요 이상의 고수준 기능 추가는 API를 복잡하게 만들 수 있다.
  • 직교성(Orthogonality)을 고려한 설계는 테스트와 유지보수를 용이하게 한다. 기능 간에 서로 독립적이도록 잘 나누는 것이 핵심이다.