Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add guidance for naming flags vs non-flags enums and cases where they should be defined side-by-side #552

Merged
merged 2 commits into from
Jul 8, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion graph/GuidelinesGraph.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,9 @@ Following is a short summary of the most often used conventions.
| :no_entry: **MUST NOT** use redundant words in names. | - **Right:** /places/{id}/**displayName** or /phones/{id}/**number** <BR> - **Wrong:** /places/{id}/**placeName** or /phones/{id}/**phoneNumber** |
| :warning: **SHOULD NOT** use brand names in type or property names. | - **Right:** chat <BR> - **Wrong:** teamsChat <BR> - **NOTE:** there is an exception for resources that *only* exist under the `/admin` root segment and the `/users/{userId}/settings` path. |
| :warning: **SHOULD NOT** use acronyms or abbreviations unless they are broadly understood. | - **Right:** url or htmlSignature <BR> - **Wrong:** msodsUrl or dlp |
| :heavy_check_mark: **MUST** use singular nouns for type names. | - **Right:** address <BR> - **Wrong:** addresses |
| :heavy_check_mark: **MUST** use singular nouns for non-enum type names. | - **Right:** address <BR> - **Wrong:** addresses |
| :heavy_check_mark: **MUST** use singular nouns for non-flags enum type names. | - **Right:** color <BR> - **Wrong:** colors |
| :heavy_check_mark: **MUST** use plural nouns for flags enum type names. | - **Right:** diplayMethods <BR> - **Wrong:** displayMethod |
| :heavy_check_mark: **MUST** use plural nouns for collections (for listing type or collection properties). | - **Right:** addresses <BR> - **Wrong:** address |
| :ballot_box_with_check: **SHOULD** pluralize the noun even when followed by an adjective (a *postpositive*).| - **Right:** passersby or mothersInLaw <BR> - **Wrong:** notaryPublics or motherInLaws |
| **CASING** | |
Expand Down
10 changes: 10 additions & 0 deletions graph/patterns/enums.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,3 +131,13 @@ With such enum, customers can select multiple values in a single field:
`displayMethod = tip | alert`

In cases where two properties want to use the same *conceptual* `EnumType`, but one property is a collection while the other is single-values, the model should define *two* separate `EnumType`s, one being a non-flags enum with a singular name and the other marked as a flags enum with its name being the plural form of the non-flags enum.

#### Flag enum + non-flag enum

There are occasions where one API will want to use a non-flag enum, but another API will want a flags enum.
For example, the `displayMethod` example above may have one API that is configuring which display methods to use, and another API which is configuring that particular display method.
In this case, the first API will want a flags enum, but the second API will want to only allow configuring one display method at a time, and will therefore prefer a non-flags enum.

Two enum types should be defined, one as a flags enum and the other as a non-flags enum.
The flags enum should be named such that it is plural, and the non-flags enum should be named such that it is singular.
The two types should be kept in sync with each other.