diff --git a/STYLE.md b/STYLE.md index b28c5da4fa..c352133c47 100644 --- a/STYLE.md +++ b/STYLE.md @@ -134,6 +134,30 @@ This section describes guidelines for designing public APIs. It can also be appl } ``` +1. When there is a significant number of arguments to a function or method, prefer to use a single options object as the argument, rather than many positional arguments. + + ```ts + // Bad + function createWidget(id: string, name: string, width: number) {} + + // Good + function createWidget(options: CreateWidgetOptions) {} + ``` + +1. Avoid arrays as return types; prefer response objects. + + ```ts + interface UserApi { + // Bad + // Can only return Users without signaling additional information such as pagination. + listUsers(): Promise; + + // Good + // Easy to evolve with additional fields. + listUsers(): Promise; + } + ``` + # Documentation Guidelines We use [API Extractor](https://api-extractor.com/pages/overview/demo_docs/) to generate our documentation, which in turn uses [TSDoc](https://github.com/microsoft/tsdoc) to parse our doc comments.