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

이 가이드는 라이브러리를 설계할 때 고려해야 할 모범 사례와 아이디어를 요약하여 담고 있습니다.

효과적인 라이브러리가 되려면 특정 기본적인 목표를 달성해야 합니다. 구체적으로는 다음을 수행해야 합니다:

• 자신의 문제 영역(problem domain)을 정의하고, 정의한 문제를 해결하는 일련의 관련 기능 요구사항(functional requirements)을 구현해야 합니다. 예를 들어, HTTP 클라이언트는 모든 HTTP 요청 타입을 지원하고 다양한 헤더, 콘텐츠 타입, 상태 코드를 이해하는 것을 목표로 할 수 있습니다.

• 문제 영역에 적합한 비기능 요구사항(non-functional criteria)을 충족해야 합니다. 이는 일반적으로 성능, 신뢰성, 보안, 유용성을 포함합니다. 이러한 기준의 상대적 중요도는 매우 다양합니다. 예를 들어, 배치 처리(batch processing)를 위해 설계된 라이브러리는 데이 트레이딩(day trading)을 위한 라이브러리와 동일한 수준의 성능을 요구하지 않을 수 있습니다.

  기능 및 비기능 요구사항을 식별하고 정의하는 과정은 소프트웨어 공학에서 광범위하게 연구된 복잡한 주제입니다. 이 가이드는 해당 주제가 범위를 벗어나므로 심층적으로 다루지 않습니다.

이 가이드의 주요 초점은 라이브러리가 사용자들에게 관련성을 유지하고 인기를 얻기 위해 갖춰야 할 특성들을 탐구하는 것입니다. 이러한 특성들은 다음과 같습니다:

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

또한, 멀티플랫폼 지원(multiplatform support)을 통해 Kotlin 라이브러리를 빌드하면 다양한 환경을 대상으로 하는 프로젝트 전반에 걸쳐 적용 가능성을 확장할 수 있습니다. 공유 코드(shared code)와 플랫폼별 코드(platform-specific code) 모두에서 안정적으로 작동하도록 API를 설계하면 지원되는 모든 타겟(targets)에서 라이브러리의 다용도성(versatility)과 유용성(usability)을 향상시킬 수 있습니다.

다음 섹션에서는 이러한 특성들을 더 깊이 파고들어, 라이브러리 사용자들에게 가능한 최고의 경험을 제공할 수 있는 방법에 대한 실용적인 조언을 제공합니다.

다음 단계

• 인지 복잡성 최소화 전략은 인지 복잡성 최소화에서 살펴보세요.
• 하위 호환성 유지에 대해서는 하위 호환성에서 알아보세요.
• 효과적인 문서화 관행에 대한 광범위한 개요는 유익한 문서화를 참조하세요.
• 멀티플랫폼 라이브러리 구축을 위한 모범 사례는 멀티플랫폼용 Kotlin 라이브러리 구축에서 확인하세요.