[이펙티브 코틀린] Item28. API 안정성을 확인하라

프로그래밍에서는 안정적이고 최대한 표준적인 API를 선호합니다. 주요 이유는 다음과 같습니다.

 

• API가 변경되면 이를 활용하는 다른 코드들에도 영향을 미친다.
• 사용자가 새로운 API를 배워야 한다.

 

버전

 

하지만 좋은 API를 한번에 설계할 수는 없으며, 이를 계속해서 개선하기 위해서 변경을 하게됩니다.

API 제작자가 'API'또는 'API의 일부'가 불안정하다면, 일반적으로 버전을 활용해서 라이브러리와 모듈의 안정성을 나타냅니다.

일반적으로 시멘틸 버저닝(Semantic Versioning, SemVer)을 사용합니다.

이 시스템은 버전 번호를 세 번호(MAJOR, MINOR, PATCH)로 나누어서 구성합니다.

 

• MAJOR 버전: 호환되지 않는 수준의 API 변경
• MINOR 버전: 이전 버전과 호환되는 기능을 추가
• PATCH 버전: 간단한 버그 수정

 

어노테이션

 

안정적인 API에 새로운 요소를 추가할 때, 아직 해당 요소가 안정적이지 않거나 실험적인 기능이라면, Experimental 메타 어노테이션을 사용해서 사용자들에게 아직 해당 요소가 안정적이지 않다는 것을 알려 주는 것이 좋습니다.

API 일부를 변경해야 한다면, 전환하는 데 시간을 두고 Deprecated 어노테이션을 활용해서 사용자에게 미리 알려줄 수 있습니다.

또한, 직접적인 대안이 있다면, IDE가 자동 전환을 할 수 있게 ReplaceWith를 붙여주는 것도 좋습니다.

 

 

---

정리

 

• 사용자는 API의 안정성에 대해 알아야 한다.
• API 변경은 수많은 사람들에게 고통을 줄 수 있다.
• API 제작자와 사용자의 커뮤니케이션이 중요하며, 이를 버전, 문서, 어노테이션 등을 통해 해결할 수 있다.