diff --git a/docs/design/NamingConventions.md b/docs/design/NamingConventions.md index f03fceca058b..d33b3fa51f07 100644 --- a/docs/design/NamingConventions.md +++ b/docs/design/NamingConventions.md @@ -4,14 +4,34 @@ This page describes the naming conventions, nouns and common terms -- Abbreviations must follow the same conventions as any other word (eg. use `DynamoDbClient`, not `DynamoDBClient`) +### Class Naming -- Use Singular Enum Name - - For enum classes or "pseudo-enums" classes(classes with public static fields), we should use singular name. (eg. use `SdkSystemSetting`, not `SdkSystemSettings`) +#### General Rules +* Prefer singular class names: `SdkSystemSetting`, not `SdkSystemSettings`. +* Treat acronyms as a single word: `DynamoDbClient`, not `DynamoDBClient`. -- Use of `Provider`, `Supplier` and `Factory` in the class name. - - For general supplier classes (loading/creating resources of the same kind), prefer `Provide` unless the class extends from Java `Supplier` class. (eg. `AwsCredentialsProvider`) - - For factories classes (creating resources of same or different kinds), prefer `Factory`. (eg. `AwsJsonProtocolFactory`) - +#### Classes that instantiate other classes + +* If the class's primary purpose is to return instances of another class: + * If the "get" method has no parameters: + * If the class implements `Supplier`: `{Noun}Supplier` (e.g. `CachedSupplier`) + * If the class does not implements `Supplier`: `{Noun}Provider` (e.g. `AwsCredentialsProvider`) + * If the "get" method has paramters: `{Noun}Factory` (e.g. `AwsJsonProtocolFactory`) + +#### Service-specific classes +* If the class makes service calls: + * If the class can be used to invoke *every* data-plane operation: + * If the class is code generated: + * If the class uses sync HTTP: `{ServiceName}Client` (e.g. `DynamoDbClient`) + * If the class uses async HTTP: `{ServiceName}AsyncClient` (e.g. `DynamoDbAsyncClient`) + * If the class is hand-written: + * If the class uses sync HTTP: `{ServiceName}EnhancedClient` (e.g. `DynamoDbEnhancedClient`) + * If the class uses async HTTP: `{ServiceName}EnhancedAsyncClient` (e.g. `DynamoDbEnhancedAsyncClient`) + * If the class can be used to invoke only *some* data-plane operations: + * If the class uses sync HTTP: `{ServiceName}{Noun}Manager` (e.g. `SqsBatchManager`) + * If the class uses async HTTP: `{ServiceName}Async{Noun}Manager` (e.g. `SqsAsyncBatchManager`) + * Note: If only the only implementation uses async HTTP, `Async` may be excluded. (e.g. `S3TransferManager`) +* If the class does not make service calls: + * If the class creates presigned URLs: `{ServiceName}Presigner` (e.g. `S3Presigner`) + * If the class is a collection of various unrelated "helper" methods: `{ServiceName}Utilities` (e.g. `S3Utilities`) \ No newline at end of file