Annotations

Annotations are a way to add metadata to your code. They are not executed by the compiler, but they can be used by other tools to generate code, generate documentation, or perform other tasks.

Why?

There are several reasons why using annotation in code can be beneficial.

One reason is to enhance code review by creating means to identify areas that need special care. For example, you can create an annotation that marks a method as deprecated, which can then be used to generate a warning to when the method is changed.

Another example is to annotate a symbol as being critical. This can be used to create awareness of when critical code is being changed and therefore to ensure that the change is reviewed by the appropriate people.

Reviewpad Annotations

Reviewpad supports the following annotations:

@reviewpad-an: <annotation>

This annotation marks a symbol with the provided <annotation>. The annotation can be any string, but it is recommended to use a short string that is unique to your project. For example, @reviewpad-an: critical.

This annotation can then be used to identify when a symbol has been changed. We can do that using the built-in hasAnnotation.

Example

Here's an example of how to use the @reviewpad-an annotation.

Let's say we want to identify all pieces of code (i.e. symbols) that are critical to our project. We can do that by adding the @reviewpad-an: critical annotation to all of the critical symbols.

package main

import "fmt"

// @reviewpad-an: critical
func main() {
  fmt.Println("Hello, World!")
}

We've marked our main function as critical symbol to our project.

Now, we can use the hasAnnotation built-in, in our Reviewpad configuration, to identify when a critical symbol has been changed, and take the appropriate action.

workflows:
  - name: changes-critical-code
    run:
      if: $hasAnnotation("critical")
      then: $warn("This pull request includes critical changes! Please review it carefully.")

Now, every time a critical symbol is changed, Reviewpad will add a warning to the pull request.

In this example, if we change the main function, because it is a critical symbol, Reviewpad will add the specified warning to the pull request.