Tenet’s are 10x shorter and faster to write than Linters

Comparison of size in code

CL

CodeLingo

L

Linter

Making tenets with CLQL that do the job of existing linters

I started learning Go and CodeLingo / CLQL at the same time, so while I have found it generally easy and straightforward to create these tenets, I feel like I could’ve knocked them out even faster if I didn’t need to look up answers to questions such as ‘what is an interface in golang?’, for example. The process has been intuitive; I think in part to having a good naming convention. I’ve had to learn what CodeLingo is, what a ‘tenet’ and a ‘flow’ is. Long story short, they are just as what they sound like they are.

Defintions taken from the project docs

tenet

A Tenet is an encoded project-specific best practice used to guide development.

(an encoded best practice)

flow

A Flow is an automated development workflow that leverages Tenets to do some task, for example automating code reviews.

(an automated workflow)

The general process of writing one tenet

Writing the CLQL

What is simple to implement in CodeLingo may be difficult for 3rd party linters, however, as this write-up should demonstrate.
Writing a tenet to describe an antipattern might be trivial in CLQL, but the corresponding linter may be orders of magnitude more complex.

The first step is usually to generate a verbose CLQL query from the CodeLingo playground.
To do this you select the part of the code you would like to match and then click the generate¹ button.
The next step is to refine that query into something that captures the logic of what you want a tenet to match.
Typically, the generated query comprises the bulk of the code you end up with. You can therefore choose what to leave in, or add new logic, depending on the needs of the tenet.

Before: Generated CLQL

This generated query contains a greater number of facts than we really need, so we can remove some of them.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import codelingo/ast/go

go.file(depth = any):
  go.decls:
    @playground.highlight
    go.func_decl:
      go.ident:
        child_count == 0
        name == "init"
        private == "true"
        public == "false"
      go.func_type:
        go.field_list:
          child_count == 0

Refining the CLQL

The process of crafting CLQL is mainly subtractive, especially for simple tenets.

@@ -2,13 +2,10 @@ import codelingo/ast/go
 
 go.file(depth = any):
   go.decls:
-    @playground.highlight
     go.func_decl:
+      @review comment
       go.ident:
-        child_count == 0
         name == "init"
-        private == "true"
-        public == "false"
       go.func_type:
         go.field_list:
           child_count == 0

After: Refined CLQL

Short and sweet.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

import codelingo/ast/go

go.file(depth = any):
  go.decls:
    go.func_decl:
      @review comment
      go.ident:
        name == "init"
      go.func_type:
        go.field_list:
          child_count == 0

See the full article here for further explanation.

Results

Comparison of size Unit tests

N/A

The original linter did not contain unit tests.

Links to source code

The work it took to write these tenets

min clicks

The number of times I needed to press generate query¹ to discover the CLQL syntax I needed.

actual clicks

The approximate number of times I ended up to pressing generate query, for exploratory purposes.

The work it took to write their unit tests

A nice surprise

• Blanket (the original linter) has a limitation. It can handle single-level selector expressions with great ease, but it doesn’t recursively dive into those selectors for a number of reasons.

  The ‘tested’ tenet, however, can find if said method was called with arbitrary nesting.

  It doesn’t actually look at the function call to make sure it is the same object that is calling. It only checks that the method being called has the same name and that it is being called within a test function and file of appropriate name.

  So it doesn’t have the same recursive limitation as blanket, but may give rise to false positives in some circumstances.

Read the full article here.