본 공통 가이드라인 문서는 다음과 같은 분들에게 유용합니다:
- 언어별 가이드라인 작성자
- 특정 언어 가이드라인이 없는 클라이언트 라이브러리 디자이너
특정 언어 가이드라인이 없는 언어로 작업하는 경우, Azure Developer Experience Architecture Board와 더욱 긴밀하게 협력하여 클라이언트 라이브러리가 적절하게 설계되고 개발자 경험이 모범적인지 확인하세요.
디자인 원칙
Azure SDK는 Azure 서비스에 연결하는 개발자의 생산성을 증대시켜야 합니다. 완성도, 확장성, 성능과 같은 부분들도 중요하지만 부수적인 것이며, 생산성은 다음과 같은 원칙들을 적용함으로서 이룰 수 있습니다:
관습적으로 (Idiomatic)
- SDK는 해당 언어의 규칙과 일반적인 디자인 가이드라인을 따라야 합니다. 해당 언어의 개발자가 자연스럽게 받아들일 수 있게 해야 합니다.
- 우리는 그 생태계의 장단점을 감수해야 합니다.
- 우리는 모든 개발자를 위해 생태계와 협력해 개선합니다.
일관성있게 (Consistent)
- 클라이언트 라이브러리는 같은 언어, 서비스, 다른 언어들끼리도 모두 일관적이어야 합니다. 충돌이 일어날 것을 생각해 언어의 일관성은 가장 높은 우선순위를 가져야 하며, 다른 언어와의 일관성은 비교적 가장 낮은 우선순위를 가집니다.
- 로깅, HTTP 통신, 에러 핸들링과 같은 서비스와 관련없는 개념들도 일관적이어야 합니다. 개발자가 다른 클라이언트 라이브러리 간 이동할 때 이러한 개념들을 다시 학습할 필요가 없게 해야 합니다.
- 클라이언트 라이브러리와 그 서비스 간 용어의 일관성은 진단하는 데 도움을 주는 좋은 것입니다.
- 서비스와 클라이언트 라이브러리 간 모든 차이점들은 일시적인 이유가 아니라 기존의 관습적인 사용을 기반으로 합당한 이유가 있어야할 것입니다.
- 각각 언어의 Azure SDK은 한 팀에서 하나의 제품이 나오는 것처럼 느껴져야 합니다.
- 해당 언어 간 동일한 기능이 있어야 합니다. 서비스의 동일한 기능보다 더 중요한 부분입니다.
접근하기쉽게 (Approachable)
- 우리는 지원하는 기술의 전문가입니다. 그래서 우리의 고객인 개발자까지 전문적인 지식을 필요로 하지는 않아도 될 것입니다.
- 개발자들이 Azure 서비스를 쉽게 성공시킬 수 있는 튜토리얼, 예제, 아티클, API 문서 등 양질의 문서를 찾아볼 수 있게 해야합니다.
- 모범 사례를 구현할 수 있는 예측 가능한 기본값들을 사용해 쉽게 시작할 수 있어야 합니다. 점진적으로 개념을 소개할 수 있게 생각해보세요.
- SDK는 해당 언어와 생태계의 가장 일반적인 매커니즘을 통해 쉽게 얻을 수 있어야 합니다.
- 개발자들이 새로운 서비스 개념을 배우는 데 사로잡힐 수 있게 해야 합니다. 핵심 사용 사례를 발견할 수 있어야 합니다.
분석가능하게 (Diagnosable)
- 개발자가 어떻게 돌아가는지 쉽게 이해할 수 있게 해야합니다.
- 어느 상황에서 네트워크 호출이 이루어지는지 인지할 수 있어야 합니다.
- 기본값들을 알 수 있어야 하며 그 의도 또한 명확해야 합니다.
- 로깅, 추적, 예외처리는 기본적이며, 신중해야 합니다.
- 에러 메시지는 간결하고, 서비스와 연관있어야 하고, 이용할 수 있어야 하며 사람이 읽을 수 있게 해야합니다.
- 해당 언어의 선호되는 디버거들과의 통합이 쉬워야 합니다.
믿음직하게 (Dependable)
- 갑작스러운 변화는 대부분의 새로운 기능보다 사용자 경험에 좋지 않으며 개선사항이 유익합니다.
- 매우 합당한 이유와 리뷰 없이 의도적으로 호환성을 깨버려서는 안됩니다.
- 호환성에 영향을 줄 수 있는 종속성에 의존해서는 안됩니다.