kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/docs/schema/verifierstyle.txt (about)

     1  // Copyright 2016 The Kythe Authors. All rights reserved.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //   http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  Verifier style guide
    16  ====================
    17  :Revision: 1.0
    18  :toc2:
    19  :toclevels: 3
    20  :priority: 999
    21  
    22  == Style guidelines
    23  
    24  * Keep to the column width of the language you are writing assertions for.
    25    The verifier's assertion language is generally whitespace-insensitive.
    26  * Test scripts should be short and check for one specific language feature.
    27    When in doubt, write a separate script.
    28  * Test scripts should not exhaustively check for all possible graph objects
    29    that a code segment should emit. Related features should be grouped together
    30    and assertions made about them in separate scripts.
    31  * Use short, meaningful names for EVars.
    32  
    33  === Avoid quotation marks in offset specifications, unless they are needed.
    34  
    35  [kythe,C++,"Quotes for most tokens are unnecessary",1,"background-color: #FFEEEE"]
    36  --------------------------------------------------------------------------------
    37  //- @"f" defines/binding _
    38  void f(int x) { }
    39  --------------------------------------------------------------------------------
    40  
    41  is less clear than
    42  
    43  [kythe,C++,"Less noise is better"]
    44  --------------------------------------------------------------------------------
    45  //- @f defines/binding _
    46  void f(int x) { }
    47  --------------------------------------------------------------------------------
    48  
    49  === Avoid the more complicated offset specifications when possible.
    50  
    51  It is better to change code snippets than to use complicated offset
    52  specifications.
    53  
    54  [kythe,C++,"f is ambiguous",1,"background-color: #FFEEEE"]
    55  --------------------------------------------------------------------------------
    56  //- @#0f defines/binding _
    57  void f(float x) { }
    58  --------------------------------------------------------------------------------
    59  
    60  is less clear than
    61  
    62  [kythe,C++,"fn is not ambiguous"]
    63  --------------------------------------------------------------------------------
    64  //- @fn defines/binding _
    65  void fn(float x) { }
    66  --------------------------------------------------------------------------------
    67  
    68  === Do not bind dangling EVars.
    69  
    70  [kythe,C++,"VarX is otherwise unconstrained",1,"background-color: #FFEEEE"]
    71  --------------------------------------------------------------------------------
    72  //- @x defines/binding VarX
    73  int x;
    74  --------------------------------------------------------------------------------
    75  
    76  is less clear than
    77  
    78  [kythe,C++,"We only care that there exists an edge of a certain kind"]
    79  --------------------------------------------------------------------------------
    80  //- @x defines/binding _
    81  int x;
    82  --------------------------------------------------------------------------------
    83  
    84  === Put shorter assertion blocks about anchors close to those anchors.
    85  
    86  [kythe,C++,"Long distances between anchors and assertions",1,"background-color: #FFEEEE"]
    87  --------------------------------------------------------------------------------
    88  //- @x defines/binding VarX
    89  int x;
    90  //- @y defines/binding VarY
    91  float y;
    92  
    93  //- VarX.node/kind variable
    94  //- VarY.node/kind variable
    95  --------------------------------------------------------------------------------
    96  
    97  is less clear than
    98  
    99  [kythe,C++,"Short distances between anchors and assertions"]
   100  --------------------------------------------------------------------------------
   101  //- @x defines/binding VarX
   102  //- VarX.node/kind variable
   103  int x;
   104  //- @y defines/binding VarY
   105  //- VarY.node/kind variable
   106  float y;
   107  --------------------------------------------------------------------------------
   108  
   109  === Prefer repeating `@` specifications for short anchors to binding EVars.
   110  
   111  [kythe,C++,"Unnecessary binding to anchors",1,"background-color: #FFEEEE"]
   112  --------------------------------------------------------------------------------
   113  void f() {
   114  //- FCallAnchor=@"f()" ref/call FnF
   115  //- FCallAnchor childof FnF
   116    f();
   117  }
   118  --------------------------------------------------------------------------------
   119  
   120  is less clear than
   121  
   122  [kythe,C++,"Repeating offset specifications"]
   123  --------------------------------------------------------------------------------
   124  void f() {
   125  //- @"f()" ref/call FnF
   126  //- @"f()" childof FnF
   127    f();
   128  }
   129  --------------------------------------------------------------------------------
   130  
   131  === Minimize use of explicit unification.
   132  
   133  Explicit unification is important in those cases where you want to check whether
   134  you are generating a particular VName. In most test scripts, you should make
   135  use of the verifier's graph search algorithm to discover VNames during
   136  execution. This makes verification tests easier to read and less brittle in
   137  the face of changing implementations for opaque identifiers.
   138  
   139  [kythe,C++,"Testing whether a type generates a specific name"]
   140  --------------------------------------------------------------------------------
   141  //- @int ref vname("int#builtin","","","","c++")
   142  using Int = int;
   143  --------------------------------------------------------------------------------
   144  
   145  is reasonable; however,
   146  
   147  [kythe,C++,"Testing whether two variables have the same type",1,"background-color: #FFEEEE"]
   148  --------------------------------------------------------------------------------
   149  //- @int ref IntType=vname("int#builtin","","","","c++")
   150  int x;
   151  //- @int ref SecondIntType=vname("int#builtin","","","","c++")
   152  int y;
   153  --------------------------------------------------------------------------------
   154  
   155  is less clear than
   156  
   157  [kythe,C++,"Testing whether two variables have the same type"]
   158  --------------------------------------------------------------------------------
   159  //- @int ref IntType
   160  int x;
   161  //- @int ref IntType
   162  int y;
   163  --------------------------------------------------------------------------------