Merge pull request #14242 from backstage/jhaals/update-styleguide

style guide: add additional examples

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<User[]>;
+
+     // Good
+     // Easy to evolve with additional fields.
+     listUsers(): Promise<ListUsersResponse>;
+   }
+   ```
+
 # 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.