diff --git a/website/src/content/docs/docs/extending-typespec/linters.md b/website/src/content/docs/docs/extending-typespec/linters.md index 3f4aac91a1f..906978f96e6 100644 --- a/website/src/content/docs/docs/extending-typespec/linters.md +++ b/website/src/content/docs/docs/extending-typespec/linters.md @@ -62,6 +62,17 @@ export const requiredDocRule = createRule({ }); ``` +#### Naming convention + +Rule names are user-facing in diagnostics, `tspconfig.yaml`, docs URLs, and suppression comments, so keep them concise and readable. + +- Use short **kebab-case** names. +- Do **not** include the package or library name in `name`. + - `name` should be only the rule part (for example `no-foo`), not `@typespec/my-linter/no-foo`. +- Use `no-` when the rule bans a construct or usage. +- Use `use-` when the rule guides users toward a standard or preferred TypeSpec pattern. +- For domain-specific validation where `no-`/`use-` does not fit, use short subject-oriented names such as `-missing-` or `-invalid-`. + #### Define rules with options Rules can accept user-configurable options via `defaultOptions` and `context.options`. When enabled with `true`, the rule uses the default options. When enabled with an object, the provided values override the defaults.