Skip to content

Commit

Permalink
Move "Exceptions" to after "Rationale" (StyraInc#245)
Browse files Browse the repository at this point in the history
IMHO it makes sense to first present *why*, then the cases for when
exceptions might make sense.

Also made H2's for these sections.

Signed-off-by: Anders Eknert <anders@styra.com>
  • Loading branch information
anderseknert authored and srenatus committed Oct 1, 2024
1 parent ded5a9a commit 9d59920
Show file tree
Hide file tree
Showing 3 changed files with 19 additions and 19 deletions.
12 changes: 6 additions & 6 deletions docs/rules/imports/avoid-importing-input.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,11 @@ allow if {
}
```

**Exceptions**
## Rationale

Using an import for `input` is not necessary, as both `input` and `data` are globally available.

## Exceptions

Using an alias for `input` can sometimes be useful, e.g. when using `input` is known to represent something specific,
like a Terraform plan. Aliasing of specific input attributes should however be avoided in favor of local assignments.
Expand All @@ -58,16 +62,12 @@ allow if {
}
```

## Rationale

Using an import for `input` is not necessary, as both `input` and `data` are globally available.

## Configuration Options

This linter rule provides the following configuration options:

```yaml
rules:
rules:
imports:
avoid-importing-input:
# one of "error", "warning", "ignore"
Expand Down
12 changes: 6 additions & 6 deletions docs/rules/style/avoid-get-and-list-prefix.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,24 +31,24 @@ developers contains user if {
}
```

**Exceptions**

Using `is_`, or `has_` for boolean helper functions, like `is_admin(user)` may be easier to comprehend than
`admin(user)`.

## Rationale

Since Rego evaluation is generally free of side effects, any rule or function is essentially a "getter". Adding a
`get_` prefix to a rule or function (like `get_resources`) thus adds little of value compared to just naming it
`resources`. Additionally, the type and return value of the rule should serve to tell whether a rule might return a
single value (i.e. a complete rule) or a collection (a partial rule).

## Exceptions

Using `is_`, or `has_` for boolean helper functions, like `is_admin(user)` may be easier to comprehend than
`admin(user)`.

## Configuration Options

This linter rule provides the following configuration options:

```yaml
rules:
rules:
style:
avoid-get-and-list-prefix:
# one of "error", "warning", "ignore"
Expand Down
14 changes: 7 additions & 7 deletions docs/rules/style/prefer-snake-case.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,24 +26,24 @@ import future.keywords.in
user_is_admin if "admin" in input.user.roles
```

**Exceptions**
## Rationale

The built-in functions use `snake_case` for naming — follow that convention for your own rules, functions, and
variables, unless you have a really good reason not to.

## Exceptions

In many cases, you might not control the format of the `input` data — if the domain of a policy (e.g. Envoy)
mandates a different style, making an exception might seem reasonable. Adapting policy format after `input` is however
prone to inconsistencies, as you'll likely end up mixing different styles in the same policy (due to imports of common
code, etc).

## Rationale

The built-in functions use `snake_case` for naming — follow that convention for your own rules, functions, and
variables, unless you have a really good reason not to.

## Configuration Options

This linter rule provides the following configuration options:

```yaml
rules:
rules:
style:
prefer-snake-case:
# one of "error", "warning", "ignore"
Expand Down

0 comments on commit 9d59920

Please sign in to comment.