From 0a2fdfa802587761295842258b00556d1e1e651e Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Thu, 20 Oct 2022 10:21:35 +0200 Subject: [PATCH 1/4] style guide: add additional example Signed-off-by: Johan Haals --- STYLE.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/STYLE.md b/STYLE.md index b28c5da4fa..1deaa7c092 100644 --- a/STYLE.md +++ b/STYLE.md @@ -134,6 +134,31 @@ This section describes guidelines for designing public APIs. It can also be appl } ``` +1. Use options as arguments to functions and methods, rather than 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. From 3c06cacd104f2228a398453e9799be500ae243b5 Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Thu, 20 Oct 2022 10:22:35 +0200 Subject: [PATCH 2/4] format Signed-off-by: Johan Haals --- STYLE.md | 1 - 1 file changed, 1 deletion(-) diff --git a/STYLE.md b/STYLE.md index 1deaa7c092..db9b2ad347 100644 --- a/STYLE.md +++ b/STYLE.md @@ -158,7 +158,6 @@ This section describes guidelines for designing public APIs. It can also be appl } ``` - # 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. From bc957dab4a35beb9bbd03da7756863614d09bacf Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Thu, 20 Oct 2022 15:00:17 +0200 Subject: [PATCH 3/4] Update STYLE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Johan Haals Co-authored-by: Fredrik Adelöw Signed-off-by: Johan Haals --- STYLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLE.md b/STYLE.md index db9b2ad347..6f1f75f324 100644 --- a/STYLE.md +++ b/STYLE.md @@ -144,7 +144,7 @@ This section describes guidelines for designing public APIs. It can also be appl function createWidget(options: CreateWidgetOptions) {} ``` -1. Avoid arrays as return types prefer response objects. +1. Avoid arrays as return types; prefer response objects. ```ts interface UserApi { From 55e9cc03bbcd5275478275352f0e7e5b75bff46c Mon Sep 17 00:00:00 2001 From: Johan Haals Date: Thu, 20 Oct 2022 15:00:23 +0200 Subject: [PATCH 4/4] Update STYLE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Johan Haals Co-authored-by: Fredrik Adelöw Signed-off-by: Johan Haals --- STYLE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/STYLE.md b/STYLE.md index 6f1f75f324..c352133c47 100644 --- a/STYLE.md +++ b/STYLE.md @@ -134,7 +134,7 @@ This section describes guidelines for designing public APIs. It can also be appl } ``` -1. Use options as arguments to functions and methods, rather than positional arguments. +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