라이브러리 저작자를 위한 가이드 소개

라이브러리 저작자를 위한 가이드 소개

이 가이드는 라이브러리를 설계할 때 고려해야 할 모범 사례와 아이디어를 정리해 둔 내용이에요.

효과적인 라이브러리가 되려면 몇 가지 근본적인 목표를 달성해야 해요. 구체적으로는 다음과 같아요:

  • 문제 도메인을 정의하고, 그 문제를 해결하는 일련의 관련 기능 요구사항을 구현해야 해요. 예를 들어 HTTP 클라이언트는 모든 HTTP 요청 타입을 지원하고, 다양한 헤더·콘텐츠 타입·상태 코드를 이해하는 것을 목표로 할 수 있어요.

  • 문제 도메인에 적합한 비기능적 기준을 충족해야 해요. 여기에는 대개 성능, 신뢰성, 보안, 사용성이 포함돼요. 이런 기준들의 상대적 중요도는 상황에 따라 크게 달라져요. 예를 들어 배치 처리를 위해 설계된 라이브러리는 데이트레이딩용으로 만들어진 라이브러리만큼의 성능을 요구하지 않을 수 있어요.

    Note:

    기능 및 비기능 요구사항을 식별하고 정의하는 과정은 소프트웨어 공학에서 폭넓게 연구된 복잡한 주제예요. 이 가이드는 그 범위를 벗어나므로 이 주제들을 깊이 다루지는 않아요.

출처: Introduction to library authors' guidelines

본문

이 가이드의 핵심 초점은 라이브러리가 사용자들에게 계속 관련성 있고 널리 사용되기 위해 가져야 할 특성을 살펴보는 것이에요. 그 특성들은 다음과 같아요:

  • 정신적 복잡성 최소화(Minimize mental complexity): 모든 개발자는 자신의 코드의 가독성과 유지보수성을 고려해야 해요. 다른 사람이 여러분의 API를 읽고, 이해하고, 사용하는 데 드는 정신적 노력을 줄이는 것이 중요해요. 이를 달성하려면 명확하고, 일관되고, 예측 가능하며, 디버깅하기 쉬운 라이브러리를 만들어야 해요.
  • 하위 호환성(Backward compatibility): API의 새 버전을 출시할 때 기존 API가 계속 동작하도록 보장해야 해요. 호환되지 않는 변경이 있다면 미리 명확하게 알리고 문서화해 주세요. 사용자가 새 API나 설계 변경을 채택할 수 있도록 간단하고 명확하며 점진적인 경로를 제공해야 해요.
  • 유익한 문서(Informative documentation): 라이브러리에 딸린 문서는 단순히 함수와 타입 선언을 반복하는 것 이상을 해야 해요. 포괄적이어야 하고, 라이브러리의 사용자층에 맞춰져야 해요. 다양한 사용자 역할의 요구와 시나리오를 정확히 반영해서, 지나치게 단순하거나 복잡하지 않으면서 필수 정보를 제공해야 해요. 설명하는 텍스트와 실용적인 코드 샘플의 균형을 맞춰서 항상 명확한 예제를 포함해야 해요.

또한 Kotlin 라이브러리를 멀티플랫폼 지원으로 만들면 다양한 환경을 대상으로 하는 프로젝트 전반에서 적용 범위를 넓힐 수 있어요. 공유 코드와 플랫폼별 코드 모두에서 안정적으로 동작하도록 API를 설계하면, 지원하는 모든 타깃에서 라이브러리의 다양성과 사용성이 향상될 수 있어요.

다음 절들에서는 이러한 특성들을 더 깊이 살펴보면서, 라이브러리 사용자에게 최상의 경험을 제공할 수 있는 실용적인 조언을 다룰 거예요.

더 알아보기