Kythe-Verifier style guide 验证样式指南

Verifier style guide 验证样式指南

Style guidelines 风格指南

• 保持为您编写断言的语言的列宽。验证器的断言语言通常是不区分空格的。
• 测试脚本应该简短，并检查一个特定的语言特性。当有疑问时，写一个单独的脚本。
• 测试脚本不用检查所有可能的图形对象(graph objects)，应该分代码段检查。
  相关的功能应该组合在一起，并在单独的脚本中对它们进行断言。
• 使用简短、有意义的 EVars 名称。

Avoid quotation marks in offset specifications, unless they are needed 除非需要，否则请避免在偏移规范中使用引号

// 引号是不必要的(C++)
//- @"f" defines/binding _
void f(int x) { }


// 不如下面的清楚
// 干扰越少越好
//- @f defines/binding _
void f(int x) { }

Avoid the more complicated offset specifications when possible 尽可能避免更复杂的偏移规格

// 最好更改代码片段，而不是使用复杂的偏移规范
// f 不明确
//- @#0f defines/binding _
void f(float x) { }


// 不如下面的清楚
// fn 没有歧义

//- @fn defines/binding _
void fn(float x) { }

Do not bind dangling EVars 不要捆绑悬挂的 EVars

// VarX is otherwise unconstrained
// VarX 在其他方面不受约束

//- @x defines/binding VarX
int x;


// 不如下面的清楚
// 我们只关心是否存在某种类型的边

//- @x defines/binding _
int x;

Put shorter assertion blocks about anchors close to those anchors 将关于锚点的较短断言块放在这些锚点附近

// Long distances between anchors and assertions (C++)
// 锚点和断言之间的距离很长

//- @x defines/binding VarX
int x;
//- @y defines/binding VarY
float y;

//- VarX.node/kind variable
//- VarY.node/kind variable


// 不如下面的清楚
// Short distances between anchors and assertions (C++)
// 锚点和断言之间的距离很短

//- @x defines/binding VarX
//- VarX.node/kind variable
int x;
//- @y defines/binding VarY
//- VarY.node/kind variable
float y;

Prefer repeating @ specifications for short anchors to binding EVars 对于短锚 首选重复@规范 而不是绑定EVAR

// Unnecessary binding to anchors (C++)
// 不必要的锚点绑定
void f() {
//- FCallAnchor=@"f()" ref/call FnF
//- FCallAnchor childof FnF
  f();
}


// 不如下面的清楚
// Repeating offset specifications (C++)
// 重复偏移规格
void f() {
//- @"f()" ref/call FnF
//- @"f()" childof FnF
  f();
}

Minimize use of explicit unification

在需要检查是否正在生成特定VName的情况下，显式统一非常重要。
在测试脚本中，您应该在执行过程中使用验证器的图形搜索算法来发现VNames。
这使得验证测试更容易阅读，并且在面对不透明标识符的不断变化的实现时不那么脆弱。

# 测试类型是否生成特定名称
//- @int ref vname("int#builtin","","","","c++")
using Int = int;
is reasonable; however,

# 测试两个变量是否具有相同的类型
//- @int ref IntType=vname("int#builtin","","","","c++")
int x;
//- @int ref SecondIntType=vname("int#builtin","","","","c++")
int y;


# 不如下面的清楚
# 测试两个变量是否具有相同的类型
//- @int ref IntType
int x;
//- @int ref IntType
int y;