Semmle QL项目中的QLDoc注释规范指南

Semmle QL项目中的QLDoc注释规范指南

codeql 项目地址: https://gitcode.com/gh_mirrors/ql/ql

前言

在Semmle QL项目中，QLDoc是一种特殊的注释格式，它不仅用于代码文档化，更是QL语言规范的重要组成部分。本文将深入解析QLDoc的最佳实践，帮助开发者编写清晰、规范的代码注释。

QLDoc基础规范

注释格式要求

1. 文档注释必须使用/** ... */格式：

   • 单行注释：/** 注释内容 */
   • 多行注释：

     /**
      * 第一行注释
      * 第二行注释
      */
     

2. 代码引用规范：

   • 所有QL代码元素（类、谓词、变量等）需用反引号包裹，如`ClassName`
   • 目标语言代码示例需使用代码块标记：

     ```java
     System.out.println("示例");
     ```
     

语言风格要求

1. 使用美式英语
2. 完整句子结构（首句可例外）
3. 避免复杂句式和学术用语
4. 禁用口语化表达和缩写形式
5. 使用通用词汇

不同类型元素的注释规范

谓词(Predicate)注释

无返回值谓词

应采用第三人称动词短语，格式为： Holds if `参数` has <属性>.

错误示范：

/** Whether `x` is valid */
/** Relates `a` to `b` */

正确示例：

/**
 * Holds if the qualifier of this call has type `qualifierType`.
 * `isExactType` indicates whether the type is exact.
 */

有返回值谓词

应采用以下格式之一：

1. Gets (a|the) <thing>.
2. 对于可能缺失的值：Gets the body of this method, if any.
3. 复杂情况可参照无返回值格式

错误示范：

/** Get a value */
/** The result is... */
/** Returns the... */

正确示例：

/**
 * Gets the expression denoting the super class of this class,
 * or nothing if this is an interface.
 */

特殊谓词

1. toString()：

   /** Gets a textual representation of this element. */
   

2. hasLocationInfo()：

   /**
    * Holds if this element is at the specified location.
    * The location spans column `startcolumn` of line `startline` to
    * column `endcolumn` of line `endline` in file `filepath`.
    */
   

废弃谓词

应在注释开头明确标注：

/** DEPRECATED: Use `newPredicate()` instead. */

内部谓词

应在注释开头标注：

/** INTERNAL: Do not use. */

类(Class)注释

应采用名词短语格式： A <领域元素> that <具有属性>.

关键点：

• 使用"that"而非"which"
• 成员元素使用单数形式
• 列出重要子类

示例：

/**
 * A delegate declaration, for example
 * ```
 * delegate void Logger(string text);
 * ```
 */

/**
 * An element that can be called.
 *
 * Either a method, a constructor, a destructor,
 * an operator, an accessor, etc.
 */

模块(Module)注释

应采用第三人称动词短语： Provides <功能描述>.

示例：

/** Provides logic for determining constant expressions. */

特殊变量引用规范

1. this的引用方式：

   • `this`
   • this <类型>

2. result的引用方式：

   • `result`
   • the result

最佳实践建议

1. 文档完整性：

   • 公共声明必须文档化
   • 非公共声明建议文档化
   • 查询文件中的声明需要文档化

2. 文件级注释：

   • 库文件(.qll)应在文件顶部添加模块注释
   • 查询文件(非测试)必须在顶部添加QLDoc查询注释

3. 清晰度优先：当规范与清晰度冲突时，以清晰度为准

通过遵循这些规范，开发者可以创建出既符合标准又易于理解的QL代码文档，这对于大型代码库的维护和团队协作尤为重要。规范的文档注释不仅能提高代码可读性，还能为自动化文档生成工具提供高质量输入。

codeql 项目地址: https://gitcode.com/gh_mirrors/ql/ql