Codify guidelines for "helper" functions.

[LarryOsterman]

Currently we have no class naming guidelines for "helper" classes.

Examples include:

• Azure::Core::Uuid
• Azure::Core::_internal::HttpShared
• Azure::Core::UserAgentGenerator
• Azure::Core::StringExtensions
• GetEnvHelper
• Azure::Security::Attestation::_detail::JsonHelpers
• Azure::Core::Credentials::_detail::AuthorizationChallengeHelper
• Azure::Core::Credentials::_internal::AuthorizationChallengeParser

Codify the use of the suffix naming so that we are consistent within the Azure SDK.

Extremely preliminary thoughts:

Type names without suffixes should represent concrete types that can be stored in another types. Examples include:

• Azure::Core::Uuid
• Azure::DateTime

These types should contain non-static methods because they represent a concrete idea.

Static-only helper types should always have a suffix.

Known suffixes include:

• Helpers - this is used for types which contain convenience methods to "help" in a task (Generating certain HTTP headers for example)
• Extensions - this is used for types which extend an existing type.
• Parser - static methods used to help parse types (this one's a bit weird - a UrlParser for instance could also be a factory for Urls)

Related guideline:

• Static-only types must have a private constructor and destructor to prevent accidental instantiation.

[github-actions[bot]]

Thank you for your feedback. Tagging and routing to the team member best able to assist.

[ahsonkhan]

Is the intent to codify this guideline meant for public surface area that we can't change/modify, or for implementation detail?

[LarryOsterman]

Is the intent to codify this guideline meant for public surface area that we can't change/modify, or for implementation detail?

This guideline is meant for the Azure SDK for C++.

It applies to all scenarios in which we might be defining types.

For instance, when considering whether a type is a helper type or not, by definition helper types should not define concrete constructs - for example, Uuid, ETag, and UserAgent - by their name, these types are values and thus can be expected to be used as a variable or class member. But UserAgentGenerator/UserAgentBuilder/UserAgentHelper are names which make it clear that they are NOT expected to be used as a variable.

Note that we could also consider defining these functions as free functions within a namespace, but that has its own set of challenges (I'm personally not a fan of free functions).