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: w3c/resource-timing#254
Change-Id: I8d54fe74418808e82b524cbf5bcb5ef18c65a4df
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2686434
Commit-Queue: Tom McKee <tommckee@chromium.org>
Reviewed-by: Yoav Weiss <yoavweiss@chromium.org>
Reviewed-by: Nicolás Peña Moreno <npm@chromium.org>
Cr-Commit-Position: refs/heads/master@{#853120}

resource-timing/CodingConventions.md

@@ -0,0 +1,59 @@
+For [Resource Timing][1] 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 adhering 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.
+*   Tests should be arranged in files according to which piece of the spec they
+    test
+*   Files should be named using a consistent pattern
+*   HTML files should 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][2]; 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`][3] 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://www.w3.org/TR/resource-timing-2/
+[2]: https://web-platform-tests.org/writing-tests/testharness-api.html#promise-tests
+[3]: https://web-platform-tests.org/writing-tests/testharness-api.html#consolidating-tests-from-other-documents