From d5a8e30c2ef1cd74922c111fd1875c5e3457eb3c Mon Sep 17 00:00:00 2001
From: Tom McKee <tommckee@chromium.org>
Date: Wed, 10 Feb 2021 11:14:34 -0800
Subject: [PATCH] Adding a CodingConventions.md file for Resource Timing

In crbug.com/1171767 we're hoping to clean up and reorganize the
Resource Timing WPT suite. Part of the cleanup is to adopt a consistent
coding style.

This change adds a markdown file with our style recommendations to the
suite itself so future developers can reference it.

Bug: 1171767
GithubIssue: https://github.com/w3c/resource-timing/issues/254
Change-Id: I8d54fe74418808e82b524cbf5bcb5ef18c65a4df
---
 resource-timing/CodingConventions.md | 57 ++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 resource-timing/CodingConventions.md

diff --git a/resource-timing/CodingConventions.md b/resource-timing/CodingConventions.md
new file mode 100644
index 000000000000000..67498ec101e5d54
--- /dev/null
+++ b/resource-timing/CodingConventions.md
@@ -0,0 +1,57 @@
+For Resource Timing tests, we want to have a consistent and clear coding style.
+The goals of this style are to
+*   make it easier for new contributors to find their way around
+*   help improve readability and maintainability
+*   help us understand which parts of the spec are tested or not
+Lots of the following rules are arbitrary but the value is realized in
+consistency instead of adhereing to the 'perfect' style.
+
+We want the test suite to be navigable. Developers should be able to easily
+find the file or test that is relevant to their work.
+*   Rearrange tests into files according to which piece of the spec they test
+*   Rename files with a consistent pattern
+*   Include useful meta tags
+    *   `<title>` for controlling labels in results pages
+    *   `<link rel="help">` to point at the relevant piece of the spec
+
+We want the test suite to run consistently. Flaky tests are counterproductive.
+*   Prefer `promise_test` to `async_test`
+    *   Note that there’s [still potential for some concurrency][1]; use
+        `add_cleanup()` if needed
+
+We want the tests to be readable. Tests should be written in a modern style
+with recurring patterns.
+*   80 character line limits where we can
+*   Consistent use of anonymous functions
+    *   prefer
+        ```
+        fn(param => {
+            body();
+        });
+        ```
+
+        over
+
+        ```
+        fn(function(param) {
+            body();
+        });
+        ```
+
+*   Prefer `const` (or, if needed, `let`) to `var`
+*   Contain use of ‘.sub’ in filenames to known helper utilities where possible
+    *   E.g. prefer use of get-host-info.sub.js to `{{host}}` or `{{ports[0]}}`
+        expressions
+*   Avoid use of webperftestharness[extension].js as it’s a layer of cognitive
+    overhead between test content and test intent
+    *   Helper .js files are still encouraged where it makes sense but we want
+        to avoid a testing framework that is specific to Resource Timing (or
+        web performance APIs, in general).
+*   Prefer [`fetch_tests_from_window`][2] to collect test results from embedded
+    iframes instead of hand-rolled `postMessage` approaches
+*   Where possible, we want tests to be scalable - adding another test case
+    should be as simple as calling the tests with new parameters, rather than
+    copying an existing test and modifying it.
+
+[1]: https://web-platform-tests.org/writing-tests/testharness-api.html#promise-tests
+[2]: https://web-platform-tests.org/writing-tests/testharness-api.html#consolidating-tests-from-other-documents