You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/copilot-instructions.md
+201Lines changed: 201 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -58,3 +58,204 @@ When reviewing tests, it is critical to:
58
58
- Check that the locations do not refer to files in the standard library, as these have issues in GitHub's Code Scanning UI and complicate our compiler compatibility tests.
59
59
- Consider the "test coverage" of the query, are each of its logical statements effectively exercised individually, collectively? The test should neither be overly bloated nor under specified.
60
60
- Consider the edge cases of the language itself, will the analysis work in non-trivial cases, are all relevant language concepts tested here? This doesn't need to be exhaustive, but it should be thoughfully thorough.
61
+
62
+
## Validating Query Style
63
+
64
+
The following list describes the required style guides for a query that **must** be validated during the code-review process.
65
+
66
+
A query **must** include:
67
+
68
+
- A use of the `isExcluded` predicate on the element reported as the primary location. This predicate ensures that we have a central mechanism for excluding results. This predicate may also be used on other elements relevant to the alert, but only if a suppression on that element should also cause alerts on the current element to be suppressed.
69
+
- A well formatted alert message:
70
+
- The message should be a complete standalone sentence, with punctuation and a period.
71
+
- The message should refer to this particular instance of the problem, rather than repeating the generic rule. e.g. "Call to banned function x." instead of "Do not use function x."
72
+
- Code elements should be placed in 'single quotes', unless they are formatted as links.
73
+
- Avoid value judgments such as "dubious" and "suspicious", and focus on factual statements about the problem.
74
+
- If possible, avoid constant alert messages. Either add placeholders and links (using $@), or concatenate element names to the alert message. Non-constant messages make it easier to find particular results, and links to other program elements can help provide additional context to help a developer understand the results. Examples:
75
+
- Instead of `Call to banned function.` prefer `Call to banned function foobar.`.
76
+
- Instead of `Return value from call is unused.` prefer `Return value from call to function [x] is unused.`, where `[x]` is a link to the function itself.
77
+
- Do not try to explain the solution in the message; instead that should be provided in the help for the query.
78
+
79
+
All lines in CodeQL source files and test files should be kept to a maximum of 100 characters.
80
+
81
+
All public predicates, classes, modules and files should be documented with QLDoc. All QLDoc should follow the following QLDoc style guide:
82
+
83
+
### General QLDoc requirements
84
+
85
+
1. Documentation must adhere to the [QLDoc specification](https://codeql.github.com/docs/ql-language-reference/ql-language-specification/#qldoc).
86
+
1. Documentation comments should be appropriate for users of the code.
87
+
1. Documentation for maintainers of the code must use normal comments.
88
+
1. Use `/** ... */` for documentation, even for single line comments.
89
+
- For single-line documentation, the `/**` and `*/` are written on the same line as the comment.
90
+
- For multi-line documentation, the `/**` and `*/` are written on separate lines. There is a `*` preceding each comment line, aligned on the first `*`.
91
+
1. Use code formatting (backticks) within comments for code from the source language, and also for QL code (for example, names of classes, predicates, and variables).
92
+
1. Give explanatory examples of code in the target language, enclosed in ```` ```<target language> ```` or `` ` ``.
93
+
94
+
95
+
### Language requirements
96
+
97
+
1. Use American English.
98
+
1. Use full sentences, with capital letters and periods, except for the initial sentence of the comment, which may be fragmentary as described below.
99
+
1. Use simple sentence structures and avoid complex or academic language.
100
+
1. Avoid colloquialisms and contractions.
101
+
1. Use words that are in common usage.
102
+
103
+
104
+
### Requirements for specific items
105
+
106
+
1. Public declarations must be documented.
107
+
1. Non-public declarations should be documented.
108
+
1. Declarations in query files should be documented.
109
+
1. Library files (`.qll` files) should have a documentation comment at the top of the file.
110
+
1. Query files, except for tests, must have a QLDoc query documentation comment at the top of the file.
111
+
112
+
### QLDoc for predicates
113
+
114
+
1. Refer to all predicate parameters in the predicate documentation.
115
+
1. Reference names, such as types and parameters, using backticks `` ` ``.
116
+
1. Give examples of code in the target language, enclosed in ```` ```<target language> ```` or `` ` ``.
117
+
1. Predicates that override a single predicate don't need QLDoc, as they will inherit it.
118
+
119
+
#### Predicates without result
120
+
121
+
1. Use a third-person verb phrase of the form ``Holds if `arg` has <property>.``
122
+
1. Avoid:
123
+
-`/** Whether ... */`
124
+
-`/** Relates ... */`
125
+
- Question forms:
126
+
-``/** Is `x` a foo? */``
127
+
-``/** Does `x` have a bar? */``
128
+
129
+
##### Example
130
+
131
+
```ql
132
+
/**
133
+
* Holds if the qualifier of this call has type `qualifierType`.
134
+
* `isExactType` indicates whether the type is exact, that is, whether
135
+
* the qualifier is guaranteed not to be a subtype of `qualifierType`.
136
+
*/
137
+
```
138
+
139
+
#### Predicates with result
140
+
141
+
1. Use a third-person verb phrase of the form `Gets (a|the) <thing>.`
142
+
1. Use "if any" if the item is usually unique but might be missing. For example
143
+
`Gets the body of this method, if any.`
144
+
1. If the predicate has more complex behaviour, for example multiple arguments are conceptually "outputs", it can be described like a predicate without a result. For example
145
+
``Holds if `result` is a child of this expression.``
146
+
1. Avoid:
147
+
-`Get a ...`
148
+
-`The ...`
149
+
-`Results in ...`
150
+
- Any use of `return`
151
+
152
+
##### Example
153
+
```ql
154
+
/**
155
+
* Gets the expression denoting the super class of this class,
156
+
* or nothing if this is an interface or a class without an `extends` clause.
157
+
*/
158
+
```
159
+
160
+
#### Deprecated predicates
161
+
162
+
The documentation for deprecated predicates should be updated to emphasize the deprecation and specify what predicate to use as an alternative.
163
+
Insert a sentence of the form `DEPRECATED: Use <other predicate> instead.` at the start of the QLDoc comment.
164
+
165
+
##### Example
166
+
167
+
```ql
168
+
/** DEPRECATED: Use `getAnExpr()` instead. */
169
+
deprecated Expr getInitializer()
170
+
```
171
+
172
+
#### Internal predicates
173
+
174
+
Some predicates are internal-only declarations that cannot be made private. The documentation for internal predicates should begin with `INTERNAL: Do not use.`
175
+
176
+
##### Example
177
+
178
+
```ql
179
+
/**
180
+
* INTERNAL: Do not use.
181
+
*/
182
+
```
183
+
184
+
#### Special predicates
185
+
186
+
Certain special predicates should be documented consistently.
187
+
188
+
- Always document `toString` as
189
+
190
+
```ql
191
+
/** Gets a textual representation of this element. */
192
+
string toString() { ... }
193
+
```
194
+
195
+
- Always document `hasLocationInfo` as
196
+
197
+
```ql
198
+
/**
199
+
* Holds if this element is at the specified location.
200
+
* The location spans column `startcolumn` of line `startline` to
201
+
* column `endcolumn` of line `endline` in file `filepath`.
0 commit comments