CodeQL查询帮助文档编写规范指南-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_01114/article/details/148440876

CodeQL查询帮助文档编写规范指南

codeql CodeQL: the libraries and queries that power security researchers around the world, as well as code scanning in GitHub Advanced Security 项目地址: https://gitcode.com/gh_mirrors/co/codeql

前言

在CodeQL静态分析工具中，查询帮助文档（.qhelp文件）是与查询配套的重要说明文件。本文将为开发者详细介绍如何编写规范、清晰且实用的查询帮助文档，帮助用户更好地理解和使用CodeQL查询。

查询帮助文档基础

文件结构与命名

查询帮助文档采用XML格式，文件扩展名为.qhelp，必须与对应的查询文件同名且位于同一目录下。基本结构如下：

<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
<qhelp>
    <!-- 内容区域 -->
</qhelp>

文档开头必须包含DOCTYPE声明和顶层<qhelp>元素。

核心内容模块

一个完整的查询帮助文档应包含以下核心部分，按顺序排列：

概述(overview)：简明扼要地描述查询检测的问题类型及其可能对程序产生的影响
建议(recommendation)：提供修复问题的具体建议和最佳实践
示例(example)：通过代码示例展示问题及解决方案
参考资料(references)：列出相关的权威参考资料

内容编写规范

语言风格要求

使用简洁明了的句子结构，避免复杂句式
避免使用口语化表达和缩写
统一使用美式英语拼写
使用通用的技术术语

代码示例规范

代码示例是帮助文档的重要组成部分，应遵循以下准则：

简洁性：示例代码应控制在20行以内，能清晰展示问题即可
位置：代码示例通常放在建议部分之后
对比展示：应同时提供"问题代码"和"修复后代码"的对比
标注清晰：明确标注哪些是错误示例，哪些是正确实践
文件引用：代码应放在单独的源文件中通过<sample>标签引用

示例格式：

<example>
<p>问题代码示例：</p>
<sample src="bad-example.java" />

<p>修复后的代码：</p>
<sample src="fixed-example.java" />
</example>

参考资料引用

参考资料应采用规范的引用格式：

书籍：

作者姓氏, 书名页码, 出版社, 出版年份.
学术论文：

作者, 论文标题, 期刊名称, 卷号(期号):页码, 年份.
网站：

网站名称: 页面标题
代码问题：对于检测代码问题的查询，应在查询文件中使用@tags标注相关编号

文档验证与测试

在提交查询帮助文档前，应使用CodeQL CLI工具进行验证：

codeql generate query-help ./query.qhelp --format=markdown

验证内容包括：

XML格式是否正确
引用的代码文件是否存在
生成结果是否符合预期

完整示例解析

以下是一个Java查询帮助文档的完整示例，展示了如何组织各模块内容：

<!DOCTYPE qhelp SYSTEM "qhelp.dtd">
<qhelp>

<overview>
<p>检测控制结构(如<code>if</code>语句或循环)中缺少大括号的情况。</p>

<p>省略大括号时，代码缩进与实际控制流的一致性尤为重要，否则可能导致逻辑错误。</p>
</overview>

<recommendation>
<p>建议所有Java控制结构都使用大括号包裹代码块，这可以：</p>
<ul>
<li>提高代码可读性</li>
<li>减少后续维护时引入错误的风险</li>
<li>避免因缩进误导导致的逻辑误解</li>
</ul>
</recommendation>

<example>
<p>错误示例：缺少大括号导致逻辑错误</p>
<sample src="MissingBracesBad.java" />

<p>正确示例：使用大括号明确代码块范围</p>
<sample src="MissingBracesGood.java" />
</example>

<references>
<li>Java编码规范：控制语句使用大括号</li>
<li>代码问题编号-483: 不正确的代码块分隔</li>
</references>

</qhelp>