Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit bebac21

Browse files
author
james
committed
add qhelp style-guide
1 parent 939db5a commit bebac21

1 file changed

Lines changed: 202 additions & 0 deletions

File tree

‎docs/query-help-style-guide.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
# Query help style-guide
2+
3+
## Introduction
4+
5+
When you contribute a new query to Semmle/ql for inclusion in the standard queries, you should also write a query help file. This file provides detailed information about the purpose and use of the query, which is available to users in LGTM (for example [here](https://lgtm.com/rules/1506093386171/)) and on the query homepages:
6+
7+
* [C/C++ queries](https://wiki.semmle.com/pages/viewpage.action?pageId=19334052)
8+
* [C# queries](https://wiki.semmle.com/display/CSHARP/C%23+queries)
9+
* [COBOL queries](https://wiki.semmle.com/display/COBOL/COBOL+queries)
10+
* [Java queries](https://wiki.semmle.com/display/JAVA/Java+queries)
11+
* [JavaScript queries](https://wiki.semmle.com/display/JS/JavaScript+queries)
12+
* [Python queries](https://wiki.semmle.com/display/PYTHON/Python+queries)
13+
14+
### Location and file name
15+
16+
Query help files must have the same base name as the query they describe and must be located in the same directory.
17+
18+
### File structure and layout
19+
20+
Query files are written using an XML format called Qhelp, and stored in a file with a `.qhelp` extension. The basic structure is as follows:
21+
22+
```
23+
<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
24+
<qhelp>
25+
CONTAINS one or more section-level elements
26+
</qhelp>
27+
```
28+
29+
The header and single top-level `qhelp` element are both mandatory.
30+
31+
### Section-level elements
32+
33+
Section-level elements are used to group the information within the query help file. All query help files should include at least the following section elements, in the order specified:
34+
35+
1. `overview`—a summary of the purpose of the query, including an explanation of what the code does and the how the behavior of the program is affected.
36+
2. `recommendation`—information on how to fix the issue highlighted by the query.
37+
3. `example`—an example of code showing the problem. Where possible, this section should also include a solution to the issue.
38+
4. `references`—relevant references to best practice.
39+
40+
For further information about the other section-level, block, list and table elements supported by the qhelp format, see [Qhelp files](https://wiki.semmle.com/display/SD/Qhelp+files).
41+
42+
43+
## English style
44+
45+
You should write the overview and recommendation elements in simple English that is easy to follow. You should:
46+
47+
* Use simple sentence structures and avoid complex or academic language.
48+
* Avoid colloquialisms and contractions.
49+
* Use US English spelling throughout.
50+
* Use words that are in common usage.
51+
52+
## Code examples
53+
54+
Whenever possible, you should include a code example that helps to explain the issue you are highlighting. Any code examples that you include should adhere to the following guidelines:
55+
56+
* The example should be less than 20 lines and ideally it should be runnable. If this is not possible, ensure that the example very clearly illustrates the issue that you are highlighting.
57+
* Put the code example after the recommendation element where possible. Only include an example in the description element if absolutely necessary.
58+
* If you are using an example to illustrate the solution to a problem, and the change required is minor, avoid repeating the whole example. It is preferable to either describe the change required or to include a smaller snippet of the corrected code.
59+
* Clearly indicate which of the samples is an example of bad coding practice and which is recommended practice.
60+
61+
There are several ways of including a code example in a query help file:
62+
63+
* Directly include the code as nested text in the `example` section, Use the `sample` block and define a `language` attribute to specify the language of the example:
64+
65+
```
66+
<example>
67+
<p>This example highlights poor coding practice</p>
68+
<sample language = "java" />
69+
70+
Example of poor code
71+
72+
<p>This example shows how to fix the code</p>
73+
<sample language = "java" />
74+
75+
Example of correct code
76+
77+
</example>
78+
```
79+
80+
81+
* Define the code example in a `src` file. The language is inferred from the file extension:
82+
83+
```
84+
<example>
85+
<p>This example highlights poor coding practice</p>
86+
87+
<sample src = "example-code-bad.java" />
88+
89+
<p>This example shows how to fix the code</p>
90+
91+
<sample src = "example-code-fixed.java" />
92+
</example>
93+
```
94+
95+
## Including references
96+
97+
You should include one or more references to provide further information about the problem that your query is designed to find. References can be of the following types:
98+
99+
### Books
100+
101+
If you are citing a book, use the following format:
102+
103+
>\<Author-initial. Surname>, _\<Book title>_ \<page/chapter etc.\>, \<Publisher\>, \<date\>.
104+
105+
For example:
106+
107+
>W. C. Wake, _Refactoring Workbook_, pp. 93 – 94, Addison-Wesley Professional, 2004.
108+
109+
Note, & symbols need to be replaced by \&amp;. The symbol will be displayed correctly in the html files generated from the qhelp files.
110+
111+
### Academic papers
112+
113+
If you are citing an academic paper, we recommend adopting the reference style of the journal that you are citing. For example:
114+
115+
>S. R. Chidamber and C. F. Kemerer, _A metrics suite for object-oriented design_. IEEE Transactions on Software Engineering, 20(6):476-493, 1994.
116+
117+
118+
### Websites
119+
120+
If you are citing a website, please use the following format, without breadcrumb trails:
121+
122+
>\<Name of website>: \<Name of page or anchor>
123+
124+
For example:
125+
126+
>Java 6 API Specification: [Object.clone()](http://docs.oracle.com/javase/6/docs/api/java/lang/Object.html#clone%28%29).
127+
128+
### Referencing potential security weaknesses
129+
130+
If your query checks code for a CWE weakness, you should use the `@tags` element in the query file to reference the associated CWEs, as explained [here](query-metadata-style-guide.md). When you use these tags, a link to the appropriate entry from the [MITRE.org](https://cwe.mitre.org/scoring/index.html) site will automatically appear as a reference in the qhelp file.
131+
132+
## Query help example
133+
134+
The following example is a qhelp file for a query from the standard query suite for Java:
135+
136+
```
137+
<!DOCTYPE qhelp PUBLIC
138+
"-//Semmle//qhelp//EN"
139+
"qhelp.dtd">
140+
<qhelp>
141+
142+
<overview>
143+
<p>A control structure (an <code>if</code> statement or a loop) has a body that is either a block
144+
of statements surrounded by curly braces or a single statement.</p>
145+
146+
<p>If you omit braces, it is particularly important to ensure that the indentation of the code
147+
matches the control flow of the code.</p>
148+
149+
</overview>
150+
<recommendation>
151+
152+
<p>It is usually considered good practice to include braces for all control
153+
structures in Java. This is because it makes it easier to maintain the code
154+
later. For example, it's easy to see at a glance which part of the code is in the
155+
scope of an <code>if</code> statement, and adding more statements to the body of the <code>if</code>
156+
statement is less error-prone.</p>
157+
158+
<p>You should also ensure that the indentation of the code is consistent with the actual flow of
159+
control, so that it does not confuse programmers.</p>
160+
161+
</recommendation>
162+
<example>
163+
164+
<p>In the example below, the original version of <code>Cart</code> is missing braces. This means
165+
that the code triggers a <code>NullPointerException</code> at runtime if <code>i</code>
166+
is <code>null</code>.</p>
167+
168+
<sample src="UseBraces.java" />
169+
170+
<p>The corrected version of <code>Cart</code> does include braces, so
171+
that the code executes as the indentation suggests.</p>
172+
173+
<sample src="UseBracesGood.java" />
174+
175+
<p>
176+
In the following example the indentation may or may not be misleading depending on your tab width
177+
settings. As such, mixing tabs and spaces in this way is not recommended, since what looks fine in
178+
one context can be very misleading in another.
179+
</p>
180+
181+
<sample src="UseBraces2.java" />
182+
183+
<p>
184+
If you mix tabs and spaces in this way, then you might get seemingly false positives, since your
185+
tab width settings cannot be taken into account.
186+
</p>
187+
188+
</example>
189+
<references>
190+
191+
<li>
192+
Java SE Documentation:
193+
<a href="http://www.oracle.com/technetwork/java/javase/documentation/codeconventions-142311.html#15395">Compound Statements</a>.
194+
</li>
195+
<li>
196+
Wikipedia:
197+
<a href="https://en.wikipedia.org/wiki/Indent_style">Indent style</a>.
198+
</li>
199+
200+
</references>
201+
</qhelp>
202+
```

0 commit comments

Comments
 (0)