Azure / Azure/azure-sdk-for-cpp

Should model types always be in the ::Models sub-namespace or remain in the same parent namespace as the clients, depending on amount of clutter?

Open
#6,192 2 comments 0 reactions 0 assignees View on GitHub
Azure.Core design-discussion
Dominant language
C++
Stars
205
Forks
172
Avg merge
1d 15m
Merged PRs (30d)
33

Description

This is a C++ design guideline question, which might also impact codegen for appconfig (FYI @antkmsft)
There seems to be a bit of inconsistency in our service SDKs on this topics.

For example, attestation has models in a `::Models` sub-namespace.
The same is true for most of our service SDKs including Storage (Blobs, Queues, etc.), Tables, and KeyVault Administration
https://github.com/Azure/azure-sdk-for-cpp/blob/ac3321c8570683a887f91c99206ddc2d3b5dde12/sdk/attestation/azure-security-attestation/inc/azure/attestation/attestation_client_models.hpp#L27-L34

But others, like the hand-written KeyVault (Keys, Secrets, Certificates) keep the models within the parent namespace:
https://github.com/Azure/azure-sdk-for-cpp/blob/ac3321c8570683a887f91c99206ddc2d3b5dde12/sdk/keyvault/azure-security-keyvault-certificates/inc/azure/keyvault/certificates/certificate_client_models.hpp#L25-L31

When we initially shipped Storage, we decided to move all models into a sub-namespace, to avoid cluttering the client namespace (but it has it as a MAY, based on the amount of types):
https://github.com/Azure/azure-sdk/issues/2010
https://github.com/Azure/azure-sdk-for-cpp/issues/959

Should we ignore the outliers, and always emit client models in a `::Models` sub-namespace going forward, or keep it flexible?

Otherwise, if we want to stick with the flexibility of having a `::Models` namespace in some cases depending on how cluttered the parent namespace can become, **we need a configurable option within the C++ code generator to opt-into generating the sub-namespace.**
And establish some "rule of thumb" guidance around when to use it.
For example, we probably don't need it for AppConfig, since there's only one client with ~20 operations and about twice as many model types, but that's reaching the boundary. .NET doesn't put them in a Models sub-namespace, but Java does put them in their own `.models` package.

cc @LarryOsterman, @RickWinter

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.