Added documentation describing guidelines for writing scope tests (#3019)

Author: AndreasArvidsson

.vscode/settings.json

@@ -28,6 +28,11 @@
     ".busted": "lua"
   },
   "files.eol": "\n",
+  "github.copilot.chat.codeGeneration.instructions": [
+    {
+      "file": "./packages/cursorless-org-docs/src/docs/contributing/scope-test-format.md"
+    }
+  ],
   "typescript.enablePromptUseWorkspaceTsdk": true,
   "typescript.tsdk": "node_modules/typescript/lib",
   // Turn off tsc task auto detection since we have the necessary tasks as npm scripts

packages/cursorless-org-docs/src/docs/contributing/scope-test-format.md

@@ -4,22 +4,16 @@ We have a custom format we use to test that our scopes are correct. The format i
 
 ## Example
 
-Example of `.scope` file for the javascript if statement scope.
+Example of `.scope` file for the javascript statement scope.
 
 ```
-if (true) {
-
-}
+const value = 0;
 ---
-
 [Content] =
 [Removal] =
-[Domain] = 0:0-2:1
-  >-----------
-0| if (true) {
-1|
-2| }
-   -<
+[Domain] = 0:0-0:16
+  >----------------<
+0| const value = 0;
 
 [Insertion delimiter] = "\n"
 ```
@@ -46,16 +40,34 @@ A description of the different ranges and how they are used is available in our
 
 ### Scope ranges
 
-The below example indicates that the content range, removal range, and domain range was the same. Line 0, column 0, to line 2, column 1. These ranges could also be different and in that case each show up as a separate range.
+The below example indicates that the content range, removal range, and domain range was the same. Line 0, column 0, to line 0, column 16.
 
 ```
 [Content] =
 [Removal] =
 [Domain] = 0:0-2:1
 ```
 
+These ranges could also be different and in that case each show up as a separate range.
+
+```
+[Removal] =
+[Content] = 0:0-0:6
+
+[Domain] = 0:0-2:1
+```
+
 Each range is also visualized:
 
+Single line range
+
+```
+  >------------<
+0| if (true) {}
+```
+
+Multi line range
+
 ```
   >-----------
 0| if (true) {
@@ -65,3 +77,38 @@ Each range is also visualized:
 ```
 
 On the left hand side we first have the line numbers, a pipe separator, and finally the source code. The range is visualized by starting after `>` and ending before `<`. Note that `>` and `<` is excluded from the range. That means a range of length one is `>-<` and an empty range is `><`.
+
+## Style guidelines
+
+For ease of readability we want all scope test to follow the recommended style guidelines.
+
+### Naming convention and values
+
+- For classes, functions and variables we use the classic: `foo`, `bar`, `baz`, `bongo`. Language specific formatting still applies. eg `Foo` for a class in Java, `IFoo` for an interface in C# etc.
+- For arguments and parameters we usually use: `aaa`, `bbb`, `ccc` and so on.
+- For data type we usually use `int` or `number`.
+- For value we usually use `0`, `1`, `2` and so on.
+
+Examples:
+
+```
+class Foo {}
+int foo = 0;
+foo(aaa, bbb);
+```
+
+### Keep it compact
+
+Don't add more lines than the example actually needs. For example if the test is about the class name, the facet `name.class`: there is no point having a lot of code in the class body or having its span multiple lines.
+
+```
+        >---<
+0| class Foo {}
+```
+
+Sometimes we actually need a body but that doesn't mean that we need it to be multiple lines. The facet `interior.class` can look like this:
+
+```
+             >-<
+0| class Foo { }
+```