Azure / Azure/azure-sdk-for-cpp

Codify guidelines for "helper" functions.

Open
#6,164 3 comments 0 reactions 1 assignee Assigned to @LarryOsterman View on GitHub
Azure.Core Client needs-team-attention
Dominant language
C++
Stars
205
Forks
172
Avg merge
1d 3h
Merged PRs (30d)
37

Description

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.

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.