LGTM Enterprise 1.25

Query help

The help for a query contains detailed information about the purpose and use of that query. Other users may be interested in a custom query you have written and added to LGTM and therefore it's important to document what your query is for, and how you can fix any potential problems that your query finds in the code. That's what the query help is for.

How do I write help for a custom query?

If you write custom queries for inclusion in LGTM analysis, it's good practice to write a help file for each query, and add it to LGTM too.

Query help files are written using a custom XML format, and stored in a file with a .qhelp extension. They must have the same base name as the query file (.ql) they relate to.

Your starting point for writing query help files is the Query help style guide, which contains a full worked example. For further information on the XML format and the structure of query help files, see Query help files.

You add a query help file at the same time, and in the same way as the related custom query. For further information, see Add the custom query and associated files to LGTM.

Where do I see the help for a query on LGTM?

There are different ways to display a Query help page, which is where you can see the help for a query in LGTM. You can:

  • Click the question mark () for the related alert on the Alerts or the My alerts tab.
  • Expand a query name on the Alerts or the My alerts tab and click Read more.
  • Search for a query and click its name in the search results.

What does the query help look like in LGTM?

The screenshot below shows an example of help for a built-in query. Click the + button to reveal the screenshot. The help for a custom query will look very similar.

The section highlighted in light purple at the top ( above) contains query properties that are defined in the query file itself (.ql file), such as the query ID, severity and assigned tags.

The query help file (.qhelp) should contain the following section elements in the following order:

  • Overview—a short summary of the issue that the query identifies, including an explanation of how it could affect the behavior of the program ( above).
  • Recommendation—information on how to fix the alert ( above).
  • Example—an example showing the problem. This section may also include a solution to the issue, as an illustration on how the problem can be solved ( above).
  • References—relevant references to best practices and useful technical information ( above).