From 538833b0d4e81be3b9fd86e64a0b6161d3db4950 Mon Sep 17 00:00:00 2001 From: Julio Castillo Date: Mon, 3 Apr 2023 11:56:44 +0200 Subject: [PATCH 1/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 050257e7..b0be2797 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -200,6 +200,10 @@ We have several such interfaces defined for IAM, log sinks, organizational polic #### Design interfaces to support actual usage +> “When developing a module, look for opportunities to take a little bit of extra suffering upon yourself in order to reduce the suffering of your users.” +> +> -- John Ousterhout in "A Philosophy of Software Design" + Variables should not simply map to the underlying resource attributes, but their **interfaces should be designed to match common use cases** to reduce friction and offer the highest possible degree of legibility. This translates into different practical approaches: From 1dce9d0aff557606c735b9a9772bd6559664026b Mon Sep 17 00:00:00 2001 From: Julio Castillo Date: Mon, 3 Apr 2023 11:58:11 +0200 Subject: [PATCH 2/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b0be2797..9e5159ec 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -202,7 +202,7 @@ We have several such interfaces defined for IAM, log sinks, organizational polic > “When developing a module, look for opportunities to take a little bit of extra suffering upon yourself in order to reduce the suffering of your users.” > -> -- John Ousterhout in "A Philosophy of Software Design" +> - John Ousterhout in "A Philosophy of Software Design" Variables should not simply map to the underlying resource attributes, but their **interfaces should be designed to match common use cases** to reduce friction and offer the highest possible degree of legibility. From cef5128f07936b11362d7494103312d99b969daa Mon Sep 17 00:00:00 2001 From: Julio Castillo Date: Mon, 3 Apr 2023 11:59:15 +0200 Subject: [PATCH 3/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9e5159ec..663a92b7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -202,7 +202,7 @@ We have several such interfaces defined for IAM, log sinks, organizational polic > “When developing a module, look for opportunities to take a little bit of extra suffering upon yourself in order to reduce the suffering of your users.” > -> - John Ousterhout in "A Philosophy of Software Design" +> \- John Ousterhout in "A Philosophy of Software Design" Variables should not simply map to the underlying resource attributes, but their **interfaces should be designed to match common use cases** to reduce friction and offer the highest possible degree of legibility. From 3d24f0999c706b46073f5ac22814df3aef7d9deb Mon Sep 17 00:00:00 2001 From: Julio Castillo Date: Mon, 3 Apr 2023 13:45:56 +0200 Subject: [PATCH 4/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 663a92b7..3a736a5b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -123,6 +123,10 @@ This section illustrates how our design principles translate into actual code. W #### Design by logical entity instead of product/feature +> “The most fundamental problem in computer science is problem decomposition: how to take a complex problem and divide it up into pieces that can be solved independently.” +> +> — John Ousterhout in "A Philosophy of Software Design" + This is probably our oldest and most important design principle. When designing a module or a FAST stage we look at its domain from a functional point of view: **what is the subset of resources (or modules for FAST) that fully describes one entity and allows encapsulating its full configuration?** It's a radically different approach from designing by product or feature, where boundaries are drawn around a single GCP functionality. @@ -202,7 +206,7 @@ We have several such interfaces defined for IAM, log sinks, organizational polic > “When developing a module, look for opportunities to take a little bit of extra suffering upon yourself in order to reduce the suffering of your users.” > -> \- John Ousterhout in "A Philosophy of Software Design" +> — John Ousterhout in "A Philosophy of Software Design" Variables should not simply map to the underlying resource attributes, but their **interfaces should be designed to match common use cases** to reduce friction and offer the highest possible degree of legibility. @@ -289,6 +293,10 @@ module "project" { ``` #### Design compact variable spaces +> "The best modules are those whose interfaces are much simpler than their implementations" +> +> — John Ousterhout in "A Philosophy of Software Design" + Designing variable spaces is one of the most complex aspects to get right, as they are the main entry point through which users consume modules, examples and FAST stages. We always strive to **design small variable spaces by leveraging objects and implementing defaults** so that users can quickly produce highly readable code. @@ -417,6 +425,10 @@ Each FAST stage should be designed so that it can optionally be used in isolatio #### Stage interfaces +> “The best modules are those that provide powerful functionality yet have simple interfaces.” +> +> — John Ousterhout in "A Philosophy of Software Design" + Stages are designed based on the concept of ["contracts" or interfaces](./fast/README.md#contracts-and-stages), which define what information is produced by one stage via outputs, which is then consumed by subsequent stages via variables. Interfaces are compact in size (few variables) but broad in scope (variables typically leverage maps), so that consumers can declare in variable types only the bits of information they are interested in. From 25b64c2b80ac6c421b803d6c3513b5dfdfaf4417 Mon Sep 17 00:00:00 2001 From: Julio Castillo Date: Mon, 3 Apr 2023 13:51:51 +0200 Subject: [PATCH 5/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a736a5b..221df606 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -206,6 +206,8 @@ We have several such interfaces defined for IAM, log sinks, organizational polic > “When developing a module, look for opportunities to take a little bit of extra suffering upon yourself in order to reduce the suffering of your users.” > +> “Providing choice is good, but interfaces should be designed to make the common case as simple as possible” +> > — John Ousterhout in "A Philosophy of Software Design" Variables should not simply map to the underlying resource attributes, but their **interfaces should be designed to match common use cases** to reduce friction and offer the highest possible degree of legibility. From e0c15d70e44554fef72eb34adbdc1ff04dbbeac8 Mon Sep 17 00:00:00 2001 From: Julio Castillo Date: Mon, 3 Apr 2023 13:59:02 +0200 Subject: [PATCH 6/6] Update CONTRIBUTING.md --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 221df606..1885c1e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -295,6 +295,7 @@ module "project" { ``` #### Design compact variable spaces + > "The best modules are those whose interfaces are much simpler than their implementations" > > — John Ousterhout in "A Philosophy of Software Design"