라이브러리 작성 가이드 소개
이 가이드는 라이브러리를 설계할 때 고려해야 할 모범 사례와 아이디어 요약을 담고 있습니다.
효과적인 라이브러리가 되기 위해서는 몇 가지 근본적인 목표를 달성해야 합니다. 구체적으로 다음과 같아야 합니다:
문제 도메인 정의 및 관련 기능 구현: 문제 도메인을 정의하고, 정의된 문제를 해결하는 일련의 관련 기능 요구 사항을 구현해야 합니다. 예를 들어, HTTP 클라이언트는 모든 HTTP 요청 유형을 지원하고 다양한 헤더, 콘텐츠 유형 및 상태 코드를 이해하는 것을 목표로 할 수 있습니다.
비기능적 기준 충족: 문제 도메인에 적합한 비기능적 기준을 충족해야 합니다. 여기에는 일반적으로 성능, 안정성, 보안 및 사용성이 포함됩니다. 이러한 기준의 상대적 중요성은 매우 다양합니다. 예를 들어, 배치 처리를 위해 설계된 라이브러리는 데이 트레이딩(day trading)용 라이브러리와 동일한 수준의 성능을 요구하지 않을 수 있습니다.
기능 및 비기능 요구 사항을 식별하고 정의하는 과정은 소프트웨어 엔지니어링에서 광범위하게 연구된 복잡한 주제입니다. 이 가이드는 이 주제가 범위를 벗어나므로 심도 있게 다루지 않습니다.
이 가이드의 주요 초점은 라이브러리가 사용자에게 계속해서 유용하고 인기 있게 유지되기 위해 갖춰야 할 특성을 탐구하는 것입니다. 이러한 특성은 다음과 같습니다:
- 정신적 복잡성 최소화(Minimize mental complexity): 모든 개발자는 코드의 가독성과 유지보수성을 고려해야 합니다. 다른 사람들이 여러분의 API를 읽고, 이해하고, 사용하는 데 필요한 정신적 노력을 줄이는 것이 중요합니다. 이를 위해서는 명확하고, 일관되고, 예측 가능하며, 디버깅하기 쉬운 라이브러리를 만들어야 합니다.
- 하위 호환성(Backward compatibility): API의 새 버전을 출시할 때 기존 API가 계속 작동하도록 보장하세요. 하위 호환성을 깨는 변경 사항(breaking changes)이 있다면 사전에 명확하게 전달하고 문서화해야 합니다. 사용자가 새로운 API나 설계 변경 사항을 채택할 수 있도록 간단하고 명확하며 점진적인 경로를 제공하세요.
- 유익한 문서화(Informative documentation): 라이브러리와 함께 제공되는 문서는 단순히 함수 및 타입 선언을 반복하는 것 이상의 역할을 해야 합니다. 문서는 포괄적이어야 하며 라이브러리의 대상 독자에게 맞게 특별히 조정되어야 합니다. 다양한 사용자 역할의 요구 사항과 시나리오를 정확하게 반영하여, 너무 단순하거나 복잡하지 않게 필수 정보를 제공해야 합니다. 항상 명확한 예제를 포함하고, 설명 텍스트와 실제 코드 샘플 간의 균형을 유지하세요.
또한, Kotlin 라이브러리를 멀티플랫폼 지원으로 구축하면 다양한 환경을 타겟팅하는 프로젝트 전반에서 활용 범위를 넓힐 수 있습니다. 공유 코드와 플랫폼별 코드 모두에서 안정적으로 작동하도록 API를 설계하면, 지원되는 모든 타겟에서 라이브러리의 다재다능함과 사용성을 향상할 수 있습니다.
다음 섹션에서는 이러한 특성들을 더 깊이 있게 살펴보고, 라이브러리 사용자에게 가능한 최상의 경험을 제공할 수 있는 실질적인 조언을 제공합니다.
다음 단계
- 정신적 복잡성 최소화에서 정신적 복잡성을 줄이기 위한 전략을 살펴보세요.
- 하위 호환성에서 하위 호환성 유지에 대해 알아보세요.
- 효과적인 문서화 관행에 대한 광범위한 개요는 유익한 문서화를 참조하세요.
- 멀티플랫폼용 Kotlin 라이브러리 구축에서 멀티플랫폼 라이브러리 구축을 위한 모범 사례를 확인해 보세요.