Skip to content

Commit 99e26b2

Browse files
mikekistlerJeffreyRichterheaths
committed
Apply suggestions from PR review
Co-authored-by: Jeffrey Richter <[email protected]> Co-authored-by: Heath Stewart <[email protected]>
1 parent 05447fc commit 99e26b2

File tree

1 file changed

+5
-5
lines changed

1 file changed

+5
-5
lines changed

azure/ConsiderationsForServiceDesign.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ As you build out your service and API, there are a number of decisions that can
8888

8989
Good names for resources, properties, operations, and parameters are essential to a good developer experience.
9090

91-
Resources are typically described by nouns. Resource and property names must be descriptive and easy to understand for end-users. Ease of understanding comes from familiarity and recognition; you should favor consistency with other Azure services, names in the product user interface, and industry standards.
91+
Resources are described by nouns. Resource and property names must be descriptive and easy for customers to understand. Ease of understanding comes from familiarity and recognition; you should favor consistency with other Azure services, names in the product's portal/user interface, and industry standards.
9292

9393
Names should aid developers in discovering functionality without having to constantly refer to documentation.
9494
Use common patterns and standard conventions to aid developers in correctly guessing common property names and meanings.
@@ -107,11 +107,11 @@ The following are recommended naming conventions for Azure services:
107107

108108
For example, `nextUrl` and not `nextURL`.
109109

110-
:ballot_box_with_check: **YOU SHOULD** use "at" suffix in names of `date-time` values.
110+
☑️ **YOU SHOULD** use "At" suffix in names of `date-time` values.
111111

112112
:ballot_box_with_check: **YOU SHOULD** use "is" prefix in names of `boolean` values.
113113

114-
:ballot_box_with_check: **YOU SHOULD** use a suffix of the unit of measurement for values with a clear unit of measurement (such as bytes, miles, and so on). Use a generally accepted abbreviation for the units (e.g. "km" rather than "kilometers") when appropriate.
114+
☑️ **YOU SHOULD** use a suffix of the unit of measurement for values with a clear unit of measurement (such as bytes, miles, and so on). Use a generally accepted abbreviation for the units (e.g. "Km" rather than "Kilometers") when appropriate.
115115

116116
:ballot_box_with_check: **YOU SHOULD** use an int for time durations and include the time units in the name.
117117

@@ -121,7 +121,7 @@ For example, `expirationDays` as `int` and not `expiration` as `date-time`.
121121

122122
:warning: **YOU SHOULD NOT** use brand names in resource or property names.
123123

124-
:warning: **YOU SHOULD NOT** use acronyms or abbreviations unless they are broadly understood.
124+
⚠️ **YOU SHOULD NOT** use acronyms or abbreviations unless they are broadly understood for example, "ID" or "URL", but not "Num" for "number".
125125

126126
:no_entry: **DO NOT** use redundant words in names.
127127

@@ -141,7 +141,7 @@ The following are recommended names for properties that match the associated des
141141

142142
### `name` vs `id`
143143

144-
The identifier of a resource should be named `id`. This holds even in the case where the identifier is assigned by the user with a PUT method.
144+
The identifier of a resource should be suffixed with `Id`. This holds even in the case where the identifier is assigned by the user with a PUT/PATCH method.
145145

146146
## Use Previews to Iterate
147147
Before releasing your API plan to invest significant design effort, get customer feedback, & iterate through multiple preview releases. This is especially important for V1 as it establishes the abstractions and patterns that developers will use to interact with your service.

0 commit comments

Comments
 (0)