perfectionist lints

perfectionist::allow_attributes↑ top

active#[allow] for a deterministically-firing lint should be removed or be #[expect]

What it does

Flags #[allow(<lints>)] when every named lint fires deterministically — a built-in rustc lint (not on the exempt list), a clippy::* / rustdoc::* lint, or a tool-namespaced lint such as perfectionist::*. Such a suppression can be resolved two ways:

1. Remove it — when the lint can no longer fire at the site (a dead suppression, e.g. clippy::too_many_arguments left on a function that has since shed its arguments).
2. Replace it with #[expect] — when the lint still fires and you want the suppression to report itself the moment it stops.

If the attribute also names a lint the rule leaves alone (an exempt or unknown lint), only the deterministic names are resolved; the rest stay under #[allow].

Crate- and module-level scopes (#![allow(...)], and outer #[allow(...)] on a mod item) are left alone by default, because a cfg-conditional body inside the scope may fire the lint in one configuration and not another — set apply_to_outer_scopes = true to opt in.

Why restrict this?

This is a stylistic preference, not a correctness issue. A suppression often outlives the problem it suppressed. #[allow] stays silent forever, including after the underlying issue is resolved, so a project accumulates stale #[allow] attributes that no longer apply. #[expect] emits unfulfilled_lint_expectations the moment the named lint stops triggering at the site — exactly when the suppression becomes dead — so routine compilation tells the author to remove it. Every #[expect] is also a self-test that the lint does fire at the site, so a future refactor that inadvertently fixes the issue is observed rather than hidden.

Interaction with Clippy

clippy::allow_attributes (restriction, off by default) also pushes #[allow] towards #[expect], but rewrites every #[allow] indiscriminately, and only towards #[expect]. This rule flags only the lints that fire deterministically, leaving lint groups and conditionally-firing lints under #[allow]. Crucially, it does not assume #[expect] is always the answer: a deterministic #[allow] may already be dead, in which case #[expect] would be unfulfilled and removal is the right fix, so the rule offers both. Reach for this rule for that precision, or clippy::allow_attributes for a blunt crate-wide sweep.

Example

Avoid:

#[allow(clippy::too_many_arguments, reason = "matches pnpm's signature")]
fn build_fetcher(/* ... */) {}

Prefer:

#[expect(clippy::too_many_arguments, reason = "matches pnpm's signature")]
fn build_fetcher(/* ... */) {}

Source: src/rules/allow_attributes.rs

perfectionist::allow_attributes_without_reason↑ top

active#[allow] / #[expect] attribute lacks an explanatory reason = "..." field

What it does

Requires every #[allow(<lints>)] and #[expect(<lints>)] attribute to carry an explanatory reason = "..." field. #[allow] and #[expect] are the two levels that fully silence a lint's output; the project's record of suppressions needs to know why each one exists.

The check is purely local — the attribute itself — and does not depend on any inherited or ambient lint level.

Why restrict this?

This is a stylistic preference, not a correctness issue. Suppressions outlive the conditions that justify them. A bare #[allow(clippy::too_many_arguments)] told the original author to ignore a complaint; six months later, no one knows whether the rationale was "matches upstream signature", "intentional over-engineering", or "we'll fix it in the next refactor". The reason field records intent at the moment of suppression, and rustc renders it back in unfulfilled_lint_expectations notes when a stale #[expect] is encountered.

Interaction with Clippy

clippy::allow_attributes_without_reason (restriction, off by default) flags a missing reason = "..." on the same two levels this rule does — #[allow] and #[expect] — and only those, so the trigger overlaps. This rule adds a quality floor Clippy lacks: min_reason_length (default 3) flags a content-free reason = "ok" that Clippy accepts, and a blank reason = "" is treated as missing. It also takes a per-lint exempt_lints list and fires regardless of the crate's MSRV, where Clippy's is gated on the lint_reasons stabilisation. For the bare presence check alone, the Clippy lint is equivalent.

Example

Avoid:

#[allow(clippy::too_many_arguments)]
fn build_fetcher(/* ... */) {}

Prefer:

#[allow(clippy::too_many_arguments, reason = "matches upstream signature")]
fn build_fetcher(/* ... */) {}

Source: src/rules/allow_attributes_without_reason.rs

perfectionist::arbitrary_source_item_ordering↑ top

activeitem in a module body sits below a section it belongs above: pub mod, then pub use, then private imports and other items

What it does

Holds the top-level items of a module body to one fixed sequence:

1. pub mod declarations,
2. pub use re-exports,
3. private imports and every other item.

An item that sits below a section it belongs above is flagged — a pub mod under a pub use, a pub use under a private import or a fn, and so on. The last section is not ordered internally: a private use and a struct may appear in either order.

Two shapes are exempt, being neither flagged nor closing the section they sit in: an extern crate declaration, which #[macro_use] extern crate foo; pins to the top of a crate root, and a #[cfg(...)]-gated use, so a trailing #[cfg(unix)] use ...; block may follow the main import block.

Only the top-level sequence of a module body is considered. Items nested deeper — inside an impl, a trait, or a function body — are out of scope.

Any explicit visibility counts as pub for the ordering, so pub(crate) mod is a pub mod declaration and pub(super) use is a pub use re-export.

Why restrict this?

This is a stylistic preference, not a correctness issue. Rust attaches no meaning to the order of items in a module body, and no layout is wrong in the abstract. The one this rule enforces answers a reader's questions in the order they ask them: what this module contains (its submodules), what it publishes (its re-exports), and only then what it borrows and how it is built. Applying it uniformly also keeps the top of every file scanning alike, and stops a new submodule from being appended wherever the diff happened to be open.

No autofix is offered. Moving an item carries its attributes, doc comment, and any comment written above it, and a pub use hoisted above a pub mod may cross an item it names — edits a reader should make deliberately.

Interaction with Clippy

clippy::arbitrary_source_item_ordering (restriction, off by default) covers adjacent ground from the other end. It is highly general: it orders many item kinds against an ordering table the project supplies and can sort alphabetically within a group. This rule takes no configuration and bakes in the single layout above. A project that wants to spell out its own ordering should prefer the Clippy lint and turn this one off in dylint.toml:

[perfectionist]
disable = ["arbitrary_source_item_ordering"]

Enabling both lets the two orderings contradict each other.

Example

Avoid: a pub mod below the pub use that re-exports from it

pub use parser::Parser;
pub mod parser;

Avoid: a private fn above a pub use

fn helper() {}
pub use parser::Parser;

Prefer:

pub mod parser;
pub mod printer;

pub use parser::Parser;
pub use printer::Printer;

use std::collections::HashMap;

fn helper() {}

Configuration: none.

Source: src/rules/arbitrary_source_item_ordering.rs

perfectionist::avoidable_string_escapes↑ top

activestring literal contains only raw-expressible escapes; prefer the raw-string form

What it does

Forbids regular string literals whose only backslash escapes are ones a raw string would express verbatim — \", \\, and \'. The autofix rewrites the literal to the raw form r"..." / r#"..."#, picking the smallest hash count that avoids a delimiter collision.

Literals inside macro invocations are covered too: every string literal in a macro call, whatever its position — including a format!-family template that contains a {...} placeholder. The rewrite is value-preserving (a raw string still parses placeholders, and {{ / }} survive verbatim), so the literal's role doesn't matter. Suppress a site where the regular form is deliberately preferred.

That includes literals a macro uses for their source spelling rather than their value, such as stringify! and dbg!, where the raw form has the same value but a different reflected text. This is intentional: code whose behaviour depends on a literal's exact spelling instead of its value is rare and a code smell; suppress it per site with #[expect(perfectionist::avoidable_string_escapes)].

Pattern-position literals in ordinary code (e.g. match s { "C:\\path" => ... }) are out of scope; only expression-position literals are rewritten. A literal written as a pattern inside a macro call (e.g. matches!(s, "C:\\path")) is rewritten anyway, since a literal's position isn't distinguished inside a macro.

Whitespace and control-character escapes (\n, \t, \r, \0) and Unicode escapes (\x.., \u{..}) are exempt — a raw string cannot express them, and the regular form is the only choice. A literal that mixes eliminable and inexpressible escapes is also left alone; the rewrite would force the author to split the literal or fall back to concat!, which loses more than it gains.

Why restrict this?

This is a stylistic preference, not a correctness issue. The rule trades one noise source (interior backslash escapes) for a slightly more elaborate string syntax. The benefit is highest in strings full of file paths, regex patterns, JSON snippets, or embedded source code — all of which would otherwise be a sea of \\ and \".

Example

Avoid:

let json = "{\"name\":\"foo\"}";
let path = "C:\\Users\\foo\\bar";

Prefer:

let json = r#"{"name":"foo"}"#;
let path = r"C:\Users\foo\bar";

Source: src/rules/avoidable_string_escapes.rs

perfectionist::bare_email↑ top

activebare email address in comment or doc comment; wrap in <...> or prefix with mailto:

What it does

Flags bare email addresses (user@example.com) in doc comments (///, //!) and regular comments (//, /* */). Wrapping in <...>, prefixing with mailto:, or both turns the address into an explicit autolink across CommonMark, GitHub-flavored markdown, and rustdoc.

A forbid style is available for projects that prefer to keep contact information out of source entirely.

Why restrict this?

This is a stylistic preference, not a correctness issue. Bare email addresses rely on the renderer's autolinkification, which is inconsistent across markdown engines. The <email> / mailto:email forms make the autolink intent explicit.

Example

Avoid:

/// Report security issues to security@example.com.

Prefer:

/// Report security issues to <security@example.com>.

Source: src/rules/bare_email.rs

perfectionist::bare_identifier_reference↑ top

activebackticked identifier in a doc comment that resolves in scope should be an intra-doc link

What it does

Flags a backticked identifier in a doc comment (`Foo`) that resolves as a Rust path in the documented item's scope but is not written as a rustdoc intra-doc link ([`Foo`]).

Only bare single identifiers whose name resolves to an item in the enclosing module's scope are flagged; a backticked word that names nothing in scope is left alone.

A publicly-reachable item that mentions a private one is reported too, with no link offered.

Why restrict this?

This is a stylistic preference, not a correctness issue. Both `Foo` and [`Foo`] render as monospaced text, so the page looks the same at a glance. The link form additionally turns the mention into a clickable cross-reference and lets rustdoc's rustdoc::broken_intra_doc_links lint catch the day a rename leaves the prose pointing at a type that no longer exists. Spelling every in-scope mention as a link keeps the documentation navigable and the references checked.

The preference is sharper where a publicly-reachable item names a private one: the name is one its reader cannot look up, and it can be renamed at will, being no part of the API it appears in. A link does not answer either objection.

Example

Avoid:

/// Installs the package described by `PackageManifest` into `Store`.
pub fn install(manifest: &PackageManifest, store: &Store) {}

Prefer:

/// Installs the package described by [`PackageManifest`] into [`Store`].
pub fn install(manifest: &PackageManifest, store: &Store) {}

Caveat: linking is not always correct

When a backticked word names a foreign symbol that merely shares its name with an in-scope item, rewriting `Foo` to [`Foo`] links to the local item — a wrong reference that still compiles. The rule therefore only suggests the link rather than applying it automatically. For an external target, write an explicit reference link instead: [`Foo`][foo-ext] plus a [foo-ext]: <url> definition.

Source: src/rules/bare_identifier_reference.rs

perfectionist::bare_issue_reference↑ top

activeambiguous bare #NNN issue / PR reference in comment

What it does

Flags bare #NNN issue / pull-request references in doc comments (///, //!) — and, when opted in, in plain // line comments. The autofix rewrites the reference; the doc_comment_form knob selects the shape (inline [#123](URL), reference [#123], a bare URL, or a <URL> autolink).

A bare #NNN is deeply ambiguous: it might be an issue, a pull request, a colour like #123, or any other numbered item, so no suggestion is ever MachineApplicable. The suggest_issue_url / suggest_pr_url knobs choose which link target(s) the autofix offers — each MaybeIncorrect — and with neither enabled the lint is help-only. The author can also resolve the ambiguity by enclosing the token in backticks (so it reads as code) or by using a spelling without a leading #.

Why restrict this?

This is a stylistic preference, not a correctness issue. A bare #123 renders as literal text in CommonMark; only GitHub's markdown flavour autolinks the token, and only when the rendering surface is itself within a GitHub repository view. The link form renders portably across rustdoc, GitHub, and any other markdown engine.

Example

Avoid:

/// Closes #123 and supersedes #124.

Prefer: (with repository = "https://github.com/owner/repo" — forge is detected from the host), picking the issue link for one and the pull-request link for the other:

/// Closes [#123](https://github.com/owner/repo/issues/123) and
/// supersedes [#124](https://github.com/owner/repo/pull/124).

Source: src/rules/bare_issue_reference.rs

perfectionist::bare_url↑ top

activebare URL in comment or doc comment; wrap in <...> or use a labelled markdown link

What it does

Flags bare http:// and https:// URLs in doc comments (///, //!) and regular comments (//, /* */). Wrapping the URL in <...> (or using the labelled [text](url) form) is the portable rendering across CommonMark, GitHub-flavored markdown, and rustdoc.

Why restrict this?

This is a stylistic preference, not a correctness issue. Bare URLs rely on the renderer's autolinkification: rustdoc renders them, GitHub renders them, but plain CommonMark does not. The <...> form is the explicit, portable spelling.

Example

Avoid:

/// See https://example.com for details.

Prefer:

/// See <https://example.com> for details.

Source: src/rules/bare_url.rs

perfectionist::clap_help_markdown↑ top

activemarkdown construct in a clap-derived doc comment leaks into --help output

What it does

Forbids markdown-specific constructs in a doc comment that clap's derive macros consume as --help text — HTML tags, inline / reference / intra-doc links, code blocks, code spans, and headings. The rule fires on the doc comment of a struct or enum deriving clap::Parser, Args, Subcommand, ValueEnum, or CommandFactory, and on the doc comments of their fields and variants.

A ValueEnum's own type-level doc comment is left alone: unlike its variant docs — clap's per-value help — it never reaches --help.

Bold, italics, and lists are not flagged by default — clap renders them as their literal characters, which usually reads cleanly — but are available through the extra_constructs knob.

The lint stays silent on a node that overrides its help text with a plain string (#[arg(help = "...")], #[command(about = "...")], ...), because the doc comment is then no longer the source of truth for --help. A node marked #[clap(verbatim_doc_comment)] instead gets a softer note that the markdown will appear verbatim in the terminal.

A project that never wants a doc comment to become --help text at all — preferring an explicit override on every command, argument, and value — can opt into the stricter require_help_override mode. It flags every clap-derived doc comment that reaches --help without such an override, markdown or not, and reports each as a single missing-override finding rather than per markdown construct. A node with no doc comment is still left alone. This mode is off by default.

Why is this bad?

By default, clap does not render doc comments through a markdown processor. The raw text is shown verbatim in the terminal --help output. Writing [`PathBuf`] produces a docs.rs link in HTML output but shows literally as [`PathBuf`] in the terminal — a classic two-audience leak. The doc comment serves both cargo doc readers and --help readers, and markdown that helps the former actively degrades the latter.

The escape hatch is to override the help text with a plain string, keeping the rich doc comment for cargo doc:

/// Builds the lockfile by walking [`Dependency`] graphs.
#[arg(help = "Builds the lockfile by walking dependency graphs.")]
pub deps: PathBuf,

Example

Avoid:

#[derive(clap::Parser)]
struct Cli {
    /// Path to the [`PackageManifest`].
    ///
    /// See [the manifest format](https://example.com/manifest).
    manifest: PathBuf,
}

Prefer: (no markdown in the help text)

#[derive(clap::Parser)]
struct Cli {
    /// Path to the package manifest.
    manifest: PathBuf,
}

Source: src/rules/clap_help_markdown.rs

perfectionist::cloning_getter↑ top

activegetter returns an owned copy of a field where a borrow would serve

What it does

Flags a getter — an inherent method taking &self whose whole body is one field of self copied out through clone, to_owned, to_string, to_vec, to_path_buf, or to_os_string — and asks for the borrowed form instead: &str for a String field, &Path for a PathBuf, &OsStr for an OsString, &CStr for a CString, &[T] for a Vec<T>, whatever the inner type borrows as under an Option or a Box, and &T otherwise.

The call has to reproduce the field's own type for a borrow to serve in its place. So a Copy field is left alone — returning it by value is the borrowed form's equal — and so is a call that renders the field rather than copying it, such as to_string on a numeric field, where no borrow of the field is a String.

An Rc or an Arc field is left alone too: cloning one bumps a refcount rather than copying what it points at, so a borrow saves nothing, and a caller that keeps the handle has to own one.

What counts as a getter is decided by the first of these that applies:

1. to_*, into_* and as_* are conversions, never getters. Each prefix carries its own promise about cost and ownership, so the copy is the name's business rather than this rule's.
2. A method named for a field of self is a getter. This is Rust's own convention for a getter's name, so no configuration overrides it.
3. Any other name is a getter where the last getter_name_patterns entry matching it says so. There is always such an entry: every list's first one covers every name.

Every clause also requires the &self receiver and no other parameter.

A method of a trait impl is left alone, since the trait fixes its signature, and so is a method produced by a macro.

Test code is left alone; set exempt_tests to false to measure it like any other code.

Why restrict this?

This is a stylistic preference, not a correctness issue. A getter that clones decides for every caller that they wanted an owned copy, and most did not: they compare, print, or pass the value on. The borrowed form serves every caller, costs nothing, and leaves the one caller that does need ownership to say so with a .to_owned() at the call site, where the reader can see the copy. It also stops the getter from advertising the field's representation: a &str getter can later be backed by a Box<str> or an interned symbol without a caller changing.

Interaction with Clippy

clippy::clone_on_copy is what catches the .clone() on a Copy field that this rule leaves alone. No Clippy lint looks at what a getter returns.

Example

Avoid:

impl Person {
    fn first_name(&self) -> String {
        self.first_name.clone()
    }
    fn middle_name(&self) -> Option<String> {
        self.middle_name.clone()
    }
}

Prefer:

impl Person {
    fn first_name(&self) -> &str {
        &self.first_name
    }
    fn middle_name(&self) -> Option<&str> {
        self.middle_name.as_deref()
    }
}

Source: src/rules/cloning_getter.rs

perfectionist::core_instead_of_std↑ top

inactiveitem named through core or alloc instead of std

What it does

Flags an item named through core:: or alloc:: when the same item is reachable through std::, and rewrites the leading crate segment to std. alloc:: paths are covered too unless also_alloc turns that half off, and individual paths can be exempted with skip_paths.

This is the counterpart of clippy::std_instead_of_core and clippy::std_instead_of_alloc, which push paths the other way — towards the narrower crate — so that a library keeps compiling without std. Enable those two on a crate that is, or may become, no_std; enable this one on a crate that has settled on std. The two directions contradict each other, so no crate wants both.

Some paths are deliberately left alone. Nothing is flagged in a #![no_std] crate, where there is no std:: to name. A path is left alone when its std:: spelling would name a different item — core::panic::PanicInfo is not std::panic::PanicInfo — and so is a macro path, because core::panic! and std::panic! are genuinely different macros. A path produced by a macro expansion is left alone as well.

Where one core token is shared by several names (use core::{fmt::Display, panic::PanicInfo};), the rewrite is offered only when every one of them is reachable through std::; otherwise the names that are get a help instead, since rewriting the shared token would change the others too.

Why restrict this?

This is a stylistic preference, not a correctness issue. Everything public in core and alloc is reachable through std, so in a crate that will always link std the spellings are interchangeable, and which one a given line uses is usually an accident — whichever crate the code was pasted from, or whichever path an editor's auto-import happened to offer. Naming one crate root throughout keeps every use line starting with the same word, and keeps an alloc:: path from requiring an extern crate alloc; that a std crate has no other use for.

Example

Avoid:

use core::fmt::Display;
use alloc::sync::Arc;

Prefer:

use std::fmt::Display;
use std::sync::Arc;

Source: src/rules/core_instead_of_std.rs

perfectionist::excessive_cognitive_complexity↑ top

activefunction body has a cognitive complexity above the configured maximum

What it does

Measures the cognitive complexity of every function and method body and flags the ones above max_complexity.

The measure is SonarSource's Cognitive Complexity, applied to Rust: a count of how much control flow a reader has to hold in their head, weighted by how deeply it is nested. Each construct adds to the score as follows.

A closure adds nothing itself but deepens the nesting of what it contains. ?, .await, return, and an unlabelled break or continue add nothing.

The score counts what the author wrote. Code produced by a macro expansion contributes nothing, so a println! or a project's own macro_rules! is as cheap as a call, though an if written inside a macro's arguments still counts. A function that is itself produced by a macro is not measured. Nested functions are measured on their own, not as part of the function that contains them.

Test code is measured like any other code; set exempt_tests to leave it alone.

Why restrict this?

This is a stylistic preference, not a correctness issue. A function that branches and loops many times over, at several levels of nesting, is doing more than one thing, and the reader has to reconstruct all of it to change any of it. The cap pushes such a function to be split into smaller ones, each named for the one thing it does, and it pushes deeply nested code to be flattened with early returns and let ... else. The metric is designed so that both moves lower the score: a match moved into its own function loses its nesting penalty, and a guard clause costs one where the if it replaces cost one per level.

Interaction with Clippy

clippy::cognitive_complexity (restriction, off by default) is a count of branches with a correction for early returns. It charges the same for a branch at the top of a function as for one five levels deep, charges every ? and every desugared while condition as a branch, and measures the expansion of a macro rather than its invocation, so a function built from a local macro_rules! can score in the hundreds. This rule scores nesting, ignores what the reader does not see, and treats a macro invocation as one step. Enable one or the other, not both.

clippy::too_many_lines and clippy::excessive_nesting measure length and depth on their own and pair well with this rule.

Example

Avoid: a nested if inside a for inside a match — the innermost if alone costs 3

fn describe(kind: Kind, items: &[Item]) -> String {
    match kind {
        Kind::Listed => {
            let mut out = String::new();
            for item in items {
                if item.visible && !item.deprecated {
                    out.push_str(&item.name);
                } else if item.deprecated {
                    out.push_str("(deprecated)");
                }
            }
            out
        }
        Kind::Counted => items.len().to_string(),
    }
}

Prefer: one function per thing, each flat

fn describe(kind: Kind, items: &[Item]) -> String {
    match kind {
        Kind::Listed => list_names(items),
        Kind::Counted => items.len().to_string(),
    }
}

fn list_names(items: &[Item]) -> String {
    items.iter().map(Item::label).collect()
}

impl Item {
    fn label(&self) -> &str {
        if self.deprecated {
            return "(deprecated)";
        }
        if self.visible { &self.name } else { "" }
    }
}

Fixing a flagged function

The diagnostic splits the score into what came from branching and what came from nesting depth. Read that split first; it says which fix is the real one.

• Mostly nesting. The function is deeply indented rather than broad. Flatten it: return early on the error, empty, and absent cases so the happy path stops drifting rightward, and replace a nested if / match with a let ... else guard. Each level removed takes its per-level penalty with it, so the score falls because the reader's burden fell.
• Mostly branching. The function is doing several independent things in one body. Move each into its own function named for the one thing it does; a match moved into its own function also sheds the nesting penalty it carried at the call site.

One shortcut is worth naming, because it is tempting. The score is measured per function body, and a call counts as one step however much stands behind it, so pulling a tangled block into a private helper always lowers the number, even when it helps the reader not at all. That moves the complexity; it does not remove it. An extraction is real only when the new function stands on its own: a name that describes one responsibility, a small interface, and no mutable state threaded back to the caller. If the helper only makes sense read together with its single call site, the tangle is still there under a new name. The goal is the reader's burden, not the number.

Source: src/rules/excessive_cognitive_complexity.rs

perfectionist::excessive_inline_tests↑ top

activeinline test code should be extracted to a separate file

What it does

Caps how much inline unit-test code a production file may carry. Inline test code — #[cfg(test)] mod X { ... } blocks, #[test] fns, #[cfg(test)] fn helpers, and any other #[cfg(test)] item — is summed per file. The default external_when_long style flags a file once its inline-test footprint crosses inline_max_lines (or the optional inline_max_fraction_of_file); external_only flags every inline test item regardless of length. A file whose top-level items are entirely test code is exempt — it is itself a valid extraction target.

An external #[cfg(test)] mod <name>; (its body in a separate file) is neutral: it is already extracted, so it neither charges the footprint nor is otherwise checked. A test module gated by a compound predicate that still implies test — #[cfg(all(test, unix))], #[cfg(all(test, feature = "..."))] — is recognised the same as a bare #[cfg(test)], so its external file is not re-flagged as inline test code in a production file.

Only the library or binary crate is checked. Integration tests (tests/), benchmarks (benches/), and examples (examples/) are separate targets, not the library or binary whose unit-test footprint this rule governs; for those compiled under cfg(test) their top-level #[test] functions are the target rather than unit tests misplaced in a production file, so they are left untouched.

Why restrict this?

This is a stylistic preference, not a correctness issue. Keeping a large test suite out of the production file means the file an editor tab, a grep hit, or a diff shows is production code rather than a wall of fixtures. The threshold is deliberately configurable because the exact budget varies by project.

Example

Avoid:

// File: foo.rs
#[cfg(test)]
mod tests {
    /* ... 200 lines of test code ... */
}

Prefer:

// File: foo.rs
mod tests;

// File: foo/tests.rs
/* ... 200 lines of test code ... */

Source: src/rules/excessive_inline_tests.rs

perfectionist::excessive_nesting↑ top

activefunction body nests constructs deeper than the configured maximum

What it does

Measures how deeply the constructs in a function or method body nest and flags the body when the deepest point is more than max_depth (default 3) levels down.

Each construct is a level: an if (an else if stays at the same level; an else body is inside), a match (its arms are inside), a for, while, or loop, a closure, the body of a let ... else, and a free-standing block such as an unsafe block or the block a let initialises from. The block that is a construct's own body is not a level of its own, so if ready { work() } is 1 level, not 2.

The depth counts what the author wrote. A construct produced by a macro expansion is not a level, though an if written inside a macro's arguments still counts; ? and .await are not levels, a for or while loop counts once, and the body of an async fn or async block is not a level of its own. A function produced by a macro is not measured, and a nested function is measured on its own.

Test code is measured like any other code; set exempt_tests to leave it alone.

Why restrict this?

This is a stylistic preference, not a correctness issue. Each level of nesting is a condition the reader has to keep true in their head while reading everything inside it; past three, the code at the deepest point can only be understood by re-reading the way in. Deep nesting almost always flattens: a guard clause or let ... else returns early instead of wrapping the rest, an arm guard folds a condition into a pattern, continue unindents a loop body. Extracting the inner levels answers it just as well, when the new function can be named for what it does rather than where it came from and needs few of the enclosing locals; one that takes most of them as parameters has moved the nesting into an argument list rather than removed it.

Interaction with Clippy

clippy::excessive_nesting (complexity, but inert until excessive-nesting-threshold is set) counts every brace pair from the crate root, mod, impl, and fn included, so a method in an impl in a module already sits at three before its first if, and one threshold has to serve files of every shape. This rule measures each function body on its own, from zero, and counts constructs rather than braces. Enable one or the other, not both.

Example

Avoid: 4 levels — for, if let, match, if

for entry in entries {
    if let Some(meta) = entry.metadata() {
        match meta.kind() {
            Kind::File => {
                if meta.len() > limit {
                    report(entry);
                }
            }
            Kind::Dir => descend(entry),
        }
    }
}

Prefer: 2 levels — a let ... else guard in place of the if let, an arm guard in place of the if

for entry in entries {
    let Some(meta) = entry.metadata() else { continue };
    match meta.kind() {
        Kind::File if meta.len() > limit => report(entry),
        Kind::File => {}
        Kind::Dir => descend(entry),
    }
}

Prefer: the same body, cut where it has a name of its own — report_or_descend is named for what it does and takes three values, none of them the loop's state. That leaves 2 levels on each side of the cut.

for entry in entries {
    if let Some(meta) = entry.metadata() {
        report_or_descend(entry, meta, limit);
    }
}

fn report_or_descend(entry: Entry, meta: Meta, limit: u64) {
    match meta.kind() {
        Kind::File => {
            if meta.len() > limit {
                report(entry);
            }
        }
        Kind::Dir => descend(entry),
    }
}

Source: src/rules/excessive_nesting.rs

perfectionist::exhaustive_error_enums↑ top

inactiveerror-shaped type is missing #[non_exhaustive]

What it does

Flags publicly-exposed error enums that lack a #[non_exhaustive] attribute. An enum is treated as an error enum when its name ends in Error (configurable) or it implements std::error::Error. Publicly-exposed sum-like structs (a single field whose type is itself an enum) follow the same rule.

"Publicly-exposed" defaults to pub items; pub(crate) and the whole-crate "every item" sweep are configurable.

Why restrict this?

This is a stylistic preference, not a correctness issue. Adding a variant to an error enum is one of the most common reasons to publish a new minor version of an error-producing library, and #[non_exhaustive] is the standard way to make that addition not a SemVer break for downstream pattern matches. Applying it up front means future variants land without a coordinated major release across the dependents that exhaustively match on the enum.

The opinion is opt-in: some projects deliberately use exhaustive error enums to force downstream consumers to handle every new variant, and binary crates have no SemVer surface to protect. The rule is therefore inactive by default — enable it per crate by adding to dylint.toml:

[perfectionist]
enable = ["exhaustive_error_enums"]

Interaction with Clippy

clippy::exhaustive_enums and clippy::exhaustive_structs (restriction, off by default) require #[non_exhaustive] on every exported enum / struct. This rule scopes that same requirement to error types — those whose name ends in Error or that implement std::error::Error — because adding a variant to an error type downstream code matches on is the breaking change #[non_exhaustive] exists to absorb, while demanding it on all exported types is usually too broad. Enable the Clippy lints instead if you do want that blanket policy.

Example

Avoid:

#[derive(Debug)]
pub enum RuntimeError {
    SerializationFailure,
}

Prefer:

#[derive(Debug)]
#[non_exhaustive]
pub enum RuntimeError {
    SerializationFailure,
}

Source: src/rules/exhaustive_error_enums.rs

perfectionist::folded_command_setter↑ top

activefold over a singular CommandExtra setter re-implements the plural

What it does

Flags a fold over a singular command_extra::CommandExtra setter where the trait declares the plural that does the same thing, and names the plural. The pairs are with_arg against with_args, with_env against with_envs, and without_env against without_envs.

Every spelling of the setter counts, a closure that only forwards to it included.

The rule names a plural only where the code can call it.

The fold's receiver has to be a place expression followed by at most one argument-less method call. VARS, list.iter() and self.names.into_iter() qualify; a longer one is left alone.

A fold inside the plural's own body is left alone where the suggestion would make the plural call itself.

Why restrict this?

This is a stylistic preference, not a correctness issue. The fold is correct and produces an identical Command.

The preference is that a fold over a builder setter makes the reader reconstruct an operation the API already names. fold is a general-purpose combinator, so meeting one obliges the reader to work out what is being accumulated and in what order before they can see that the answer is "these variables are removed". without_envs says that outright, and the receiver stops being an accumulator threaded through a closure.

The fold form also has more places to get wrong. A fold whose closure swaps its accumulator and item, or returns the wrong one of the two, compiles in some shapes and silently builds the wrong command. The plural has no such surface.

command-extra defines each plural as the fold of its singular, so a hand-rolled fold is not an alternative to the plural but its body, inlined.

Applicability

The fix is applied only where it is known to compile and to behave as the fold did. Elsewhere the suggestion is advice, with a help line saying what to check first.

The suggestion keeps the receiver's call unless the plural makes that same call itself.

Example

Avoid:

INHERITED_VARS
    .iter()
    .fold(Command::new("cargo"), CommandExtra::without_env)

Prefer:

Command::new("cargo").without_envs(INHERITED_VARS.iter())

Avoid:

flags
    .iter()
    .fold(Command::new("ls"), |command, flag| command.with_arg(flag))

Prefer:

Command::new("ls").with_args(flags.iter())

Configuration: none.

Source: src/rules/folded_command_setter.rs

perfectionist::import_granularity_mismatch↑ top

activeimport granularity does not match the configured import_granularity_mismatch.style

What it does

Enforces a single project-wide import-granularity style, chosen via style:

• crate — one use per crate root, with every shared prefix collapsed into nested braces (use std::{collections::HashMap, io::Read};).
• module (default) — one use per leaf module; items from the same module are merged into one braced list while sibling modules sit on their own lines (use std::collections::{BTreeMap, HashMap};).
• item — one use per leaf path (use std::collections::BTreeMap;).

The names map one-to-one onto rustfmt's unstable imports_granularity (Crate / Module / Item). Only use statements that sit next to each other in a module body, share a visibility, and carry matching attributes are merged; the three respect_* knobs tighten or loosen that grouping.

Under crate style a name that is both an item and a module (use crate::thing; next to use crate::thing::T;) has two valid one-use shapes — the self-fold crate::thing::{self, T} and the sibling-split crate::{thing, thing::T} — that bind different namespaces. By default neither single-statement form is flagged and both are offered when a merge is forced; the optional self_merge knob (fold / split) picks one and enforces it.

Globs (use foo::*) are governed by perfectionist::wildcard_imports, not by this rule: a top-level glob is left alone under item.

Why restrict this?

This is a stylistic preference, not a correctness issue. None of the three shapes is wrong in the abstract — the violation is a mismatch with the project's configured style. Enforcing one keeps use blocks scanning uniformly and makes import diffs predictable. rustfmt can enforce the same shape, but only on the nightly channel; this lint gives stable-toolchain projects a hard CI check instead of a silent reformat.

Example

Style: Module (default)

Avoid:

use std::collections::HashMap;
use std::collections::BTreeMap;

Prefer:

use std::collections::{BTreeMap, HashMap};

Style: Crate

Avoid:

use std::collections::{BTreeMap, HashMap};
use std::io::Read;

Prefer:

use std::{collections::{BTreeMap, HashMap}, io::Read};

Style: Item

Avoid:

use std::collections::{BTreeMap, HashMap};

Prefer:

use std::collections::BTreeMap;
use std::collections::HashMap;

Source: src/rules/import_granularity_mismatch.rs

perfectionist::import_grouping_mismatch↑ top

inactiveimport grouping does not match the configured import_grouping_mismatch.style

What it does

Enforces a single project-wide grouping style for the run of use statements at the top of a module body. The rule is inactive by default; a project opts in and sets style to one of:

• single_block — every use sits in one contiguous block with no blank lines between imports, except that #[cfg(...)]-gated imports are carved into their own trailing block (one blank line below the rest). Set cfg_block_handling = "merge" to keep them in the one block.
• multi_block — imports are partitioned into ordered groups separated by exactly one blank line. The group set, in order, is std (std / core / alloc / proc_macro / test), internal (crate / super / self), then third-party (every other crate). A bare-path import of a first-party submodule (mod error; use error::Foo;) is classified as internal, not third-party: a bare first segment that names a mod declared in the same module scope is recognised as first-party. The order and cfg_block_handling knobs tune the partition; the inner ordering within each group is left to cargo fmt.

Orthogonally to style, the reexports knob controls pub re-exports — any use with an explicit visibility. Like style it is mandatory once the rule is enabled, and is one of: grouped, which pulls every re-export into one contiguous leading block above the private imports, visibility outranking path and cfg gating; split, which breaks that block into two — submodule re-exports (pub use child::Item;, a multi-segment path) above alias re-exports (pub use Item; / pub use Item as Alias;, a single-segment path); or by_path, which gives re-exports no dedicated block, classifying each by its path like a private import.

This rule only governs the partitioning of imports into blocks. Whether items within each use are merged or split is the job of perfectionist::import_granularity_mismatch.

Why restrict this?

This is a stylistic preference, not a correctness issue. Neither layout is wrong in the abstract — the violation is a mismatch with the project's configured style. Enforcing one keeps import blocks scanning uniformly and makes import diffs predictable. rustfmt's group_imports option can enforce the same shape, but only on the nightly channel; this lint gives stable-toolchain projects a hard CI check instead of a silent reformat. The rule is inactive by default; enable it and pick a style in dylint.toml:

[perfectionist]
enable = ["import_grouping_mismatch"]

["perfectionist::import_grouping_mismatch"]
style = "multi_block"
reexports = "grouped"

Example

Style: Multi block

Avoid:

use clap::Parser;
use std::time::Duration;
use crate::args::Args;

Prefer:

use std::time::Duration;

use crate::args::Args;

use clap::Parser;

Style: Single block

Avoid:

use std::time::Duration;

use crate::args::Args;

use clap::Parser;

Prefer: (one contiguous block; inner order left to cargo fmt)

use clap::Parser;
use crate::args::Args;
use std::time::Duration;

Style: Single block, #[cfg]-gated imports

Avoid: (cfg-gated imports mixed into the one block)

use std::fs::Metadata;
#[cfg(unix)]
use std::os::unix::fs::MetadataExt;
use super::size::Bytes;

Prefer: (cfg-gated imports kept in a trailing block)

use std::fs::Metadata;
use super::size::Bytes;

#[cfg(unix)]
use std::os::unix::fs::MetadataExt;

Re-exports in their own block (reexports = "grouped")

Avoid: (a pub use re-export mixed in with private imports)

pub use reflection::Reflection;
use super::size;

Prefer: (re-exports kept in their own leading block)

pub use reflection::Reflection;

use super::size;

Split re-exports (reexports = "split")

Avoid: (submodule re-exports and alias re-exports intermixed)

pub use Reflection as HardlinkListReflection;
pub use iter::Iter;
pub use reflection::Reflection;

Prefer: (submodule re-exports lead, alias re-exports follow)

pub use iter::Iter;
pub use reflection::Reflection;

pub use Reflection as HardlinkListReflection;

Source: src/rules/import_grouping_mismatch.rs

perfectionist::impure_macro_arguments↑ top

activemacro invocation passes an impure expression that should be bound to a let first

What it does

Flags impure expressions passed as top-level arguments to a function-like (name!(...)) or array-like (name![...]) macro invocation. The fix is to bind the expression to a let first and pass the binding instead, guaranteeing exactly-once evaluation.

Curly-brace invocations (name! { ... }) are out of scope: by convention they are DSL bodies (thread_local! { ... }, quote! { ... }, html! { ... }) where the evaluation contract is the macro's, not the call site's.

Why is this bad?

A function-like or array-like macro may evaluate any top-level argument zero, one, or many times depending on its matcher. Functions guarantee exactly-once evaluation per argument; macros do not, even when the call shape looks identical. The classic case is debug_assert_eq!:

debug_assert_eq!(map.insert(key, value), None, "duplicate");

In debug builds the call runs and the assertion holds. In release builds debug_assertions is off, the body folds to if false { ... }, and the argument expressions are not evaluated — insert never runs and the map ends the function in a state the author did not intend. The bug only surfaces under --release.

The same trap covers any macro that expands its capture more than once (min!/max!-style, retry loops): a side-effecting expression repeated produces wrong results.

Terminology

In this rule, pure means safe for the surrounding macro to drop or duplicate: evaluating the argument zero, one, or many times is observationally equivalent. Impure is anything else, and is what the rule flags.

The classification is syntactic: the rule recognises a curated set of shapes known to satisfy the property and treats everything else as impure. A const fn call, a Result::map chain over a pure base, or vec.fold(...) is therefore impure under this rule unless its shape is recognised — the lint cannot prove side-effect-freedom in general, only spot it. The trade-off favours flagging side-effect-free expressions over silently passing a real hazard. The set is narrower than the functional-programming notion of purity and is keyed to what a macro can actually do with its captures, not to side-effect-freedom in the abstract.

The recognised pure shapes are: literals, paths, field accesses, indexing of pure bases, dereferences, references, the logical / bitwise not of a pure expression (!ready), casts, the unit literal (), parenthesised / tuple / array-literal / array-repeat groups whose elements are all pure, binary chains of pure operands joined by side-effect-free operators, zero-arg method calls whose name is in the curated pure-getter set (len, is_empty, as_str, as_bytes, as_ref, as_mut, as_deref, as_slice, plus anything in extra_pure_methods), and calls to core / std macros whose expansion is a compile- time constant (concat!, env!, option_env!, include_str!, include_bytes!, stringify!, cfg!, line!, column!, file!, module_path!, plus anything in extra_pure_macros). A comparison like vec.len() <= cap evaluates the same way regardless of how many times the macro touches it, so binding it to a let would only force the comparison to run in release builds for no benefit; the same logic applies to env!("HOME") inside debug_assert_eq!(...) — there is nothing to evaluate at runtime.

Example

Bad:

debug_assert_eq!(map.insert(key, value), None, "duplicate");

Good:

let ejected = map.insert(key, value);
debug_assert_eq!(ejected, None, "duplicate");

Source: src/rules/impure_macro_arguments.rs

perfectionist::lint_attribute_trailing_comment↑ top

activetrailing comment on a lint-level attribute should be lifted into a reason = "..." field

What it does

When a lint-level attribute (#[allow], #[expect], #[warn], #[deny], #[forbid]) carries a trailing // ... line comment — on the same source line as the attribute's closing ] — that documents why the level was chosen, lifts the comment into the attribute's reason = "..." field and removes the original comment.

Only the trailing placement counts: a same-line comment after ] is unambiguously about the attribute. A comment on the preceding line is intentionally out of scope — it is just as often documentation for the next item as it is attribute rationale, and a static check cannot tell the two apart.

Doc comments (///, //!) and block comments (/* ... */) are out of scope.

Why restrict this?

This is a stylistic preference, not a correctness issue. reason = "..." is part of the attribute and travels with it through every refactor; a free-floating comment can be separated from its attribute by an unrelated edit. Compiler diagnostics render the reason field in the lint's message, so the rationale reaches the reader at the moment of confusion. One canonical location for the rationale also removes the "is this comment for the attribute, or for the next item?" question.

Example

Avoid:

#[allow(clippy::too_many_arguments)] // matches upstream signature
fn build_fetcher(/* ... */) {}

Prefer:

#[allow(clippy::too_many_arguments, reason = "matches upstream signature")]
fn build_fetcher(/* ... */) {}

Configuration: none.

Source: src/rules/lint_attribute_trailing_comment.rs

perfectionist::macro_trailing_comma↑ top

activemacro invocation does not follow rustfmt's vertical trailing-comma policy

What it does

For function-like macro invocations whose top-level arguments are comma-separated, enforces rustfmt's trailing_comma = "Vertical" policy that rustfmt itself does not apply inside macro bodies: multi-line invocations must end with a trailing comma; single-line invocations must not.

Eligibility is name-based — a curated list of core / std and well-known third-party macros (vec!, format!, println!, assert_eq!, dbg!, log::info!, tracing::debug!, anyhow::bail!, maplit::hashmap!, ...), extended via extra_macros and overridden via ignore.

Attribute-style invocations (#[derive(...)], #[serde(...)], etc.) are out of scope.

Why restrict this?

This is a stylistic preference, not a correctness issue. rustfmt's default trailing_comma = "Vertical" policy keeps argument lists uniform: every multi-line list ends with a comma, every single-line list does not. rustfmt opts out of macro bodies because a macro matcher can make the trailing comma load-bearing; for the curated macros covered by this lint, it cannot, and the policy applies without risk.

Multi-line invocations whose first top-level token starts on the opening-delimiter line (visual-indent / compact layout, e.g. vec![Inner { ... }]) are skipped: rustfmt's Vertical policy only adds a trailing comma when each top-level item is on its own line, separate from the delimiter, and strips any comma added to the compact shape. The two tools have to agree.

Example

Avoid:

let xs = vec![
    1,
    2,
    3
];
let ys = vec![1, 2, 3,];

Prefer:

let xs = vec![
    1,
    2,
    3,
];
let ys = vec![1, 2, 3];

Source: src/rules/macro_trailing_comma.rs

perfectionist::mutating_command_builder↑ top

activea command setter taking &mut self where command-extra's by-value form exists

What it does

Flags a setter called on an owned command — arg, args, env, envs, env_remove, env_clear, current_dir, stdin, stdout, stderr — and names the command_extra::CommandExtra counterpart that takes self instead of &mut self. Any command the trait covers counts: std::process::Command, a Box of one, and, behind a feature apiece, tokio::process's and async_process's.

A receiver it could not take ownership of — a &mut Command, or a field reached through one — is left alone. So is a crate that neither depends on command-extra nor belongs to a workspace declaring it; command_extra_dependency sets how far the lint looks for that declaration. Where command-extra is in the build at all, a chain is left alone unless every setter in it has a counterpart there — the by-value forms arrived over several releases, and a chain is ported whole or not at all.

A fix is applied where the whole change is known: a chain is rewritten at once, never in part. Elsewhere the diagnostic describes the change, and may show the rename without applying it.

Why restrict this?

This is a stylistic preference, not a correctness issue. Both forms build the same command, and the standard library's form is not wrong.

The preference is that a builder whose steps each yield a value composes with everything else, and one whose steps yield a borrow composes with nothing. Because Command's setters return &mut Command, a chain of them cannot be returned from a function, cannot initialise a let in one expression, cannot fill a struct field, and cannot be an accumulator. Each of those forces a mut binding whose only job is to exist until the settings are done. The by-value form removes that intermediate.

Example

Avoid:

fn lister(dir: &Path) -> Command {
    let mut command = Command::new("ls");
    command
        .current_dir(dir)
        .args(["-l", "-a"])
        .env("LANG", "C");
    command
}

Prefer:

fn lister(dir: &Path) -> Command {
    Command::new("ls")
        .with_current_dir(dir)
        .with_args(["-l", "-a"])
        .with_env("LANG", "C")
}

Source: src/rules/mutating_command_builder.rs

perfectionist::named_prelude_imports↑ top

activenamed item cherry-picked from a prelude module instead of glob-imported

What it does

Flags a use statement that cherry-picks a named item out of a prelude module (use serde::prelude::Serialize;) and leaves the glob form (use serde::prelude::*;) alone. The set of segment names treated as preludes is configurable via prelude_segment_names (default ["prelude"]), and individual prelude paths can be exempted with allowed_paths.

This is the dual of perfectionist::wildcard_imports: that rule restricts globs in general but lets preludes glob freely, while this rule restricts named imports from a prelude and lets the glob form through.

Why restrict this?

This is a stylistic preference, not a correctness issue. A prelude module is, by convention, a curated set of items the crate author decided should always travel together as a glob. Cherry-picking individual items from a prelude defeats that intent and usually means the importer should reach into the prelude's source module instead.

One rewrite covers the whole use: a statement with several cherry-picks carries it once, and a help on the rest. Where the rewrite cannot be shown to preserve what the use binds, only the help is offered.

Example

Avoid:

use serde::prelude::Serialize;
use diesel::prelude::{table, AsChangeset};

Prefer:

From the canonical module: import each item where it actually lives.

use serde::Serialize;
use diesel::{table, AsChangeset};

As a prelude glob: pull in the whole curated set at once.

use diesel::prelude::*;

Source: src/rules/named_prelude_imports.rs

perfectionist::needless_borrowed_parameters↑ top

activeborrowed parameter is only used to produce its owned form

What it does

Flags a function or method parameter taken by shared reference (&str, &Path, &OsStr, &CStr, &[T]) whose only use in the body is to produce its owned counterpart (String, PathBuf, OsString, CString, Vec<T>) — via to_owned, to_string, to_path_buf, to_vec, to_os_string, clone, into, or String::from(..) and friends. Such a parameter should take the owned form directly.

Only the conservative single-use case is flagged: the parameter must be referenced exactly once, that use must be the conversion, and the conversion must execute unconditionally — no if / match / loop, closure, or short-circuiting && / || may sit between it and the enclosing function. This is deliberately conservative: even the always-executed if condition and match scrutinee positions count as disqualifying, not just the branch arms.

Test code and build scripts are exempt by default; exempt_tests and exempt_build_scripts turn either off.

Why restrict this?

This is a stylistic preference, not a correctness issue. Taking the borrowed form and converting inside the body forces a copy even when the caller already owns the value. Taking the owned form moves the caller's value straight in; a caller that holds only a borrow performs the very same conversion at the call site that the borrowed signature was performing internally. The total number of copies is identical for the worst caller and one cheaper for the best caller.

Interaction with Clippy

clippy::needless_pass_by_value (pedantic, off by default) covers the opposite direction: a by-value parameter that is never consumed should be taken by reference. clippy::ptr_arg (style, on by default) is orthogonal — it rewrites a &String / &Vec<T> / &PathBuf parameter to the more permissive &str / &[T] / &Path. Neither moves a borrowed parameter to its owned form, so enabling all three gives full coverage of the owned-vs-borrowed trade-off.

Example

Avoid:

fn push_path(list: &mut Vec<PathBuf>, item: &Path) {
    list.push(item.to_path_buf());
}

Prefer:

fn push_path(list: &mut Vec<PathBuf>, item: PathBuf) {
    list.push(item);
}

Source: src/rules/needless_borrowed_parameters.rs

perfectionist::overly_complex_condition↑ top

activecondition has more boolean operators than the configured maximum

What it does

Counts the boolean operators (&&, ||) in the condition of an if, if let, while, while let, or match-arm guard, and flags the condition when the count is above max_operators.

Only the condition itself is counted, not the branches it selects, and a closure inside the condition is a scope of its own. An && with a let on either side of it is not counted, since no binding can replace it. A condition produced by a macro expansion is not measured, though a condition written inside a macro's arguments is. The let that binds a boolean is not a condition, so naming the expression is what satisfies the rule.

Why restrict this?

This is a stylistic preference, not a correctness issue. A condition of that many clauses is a predicate the author had in mind but did not write down; the reader has to reconstruct it from the clauses, and a later editor has to work out which clause to change. Binding the predicate, or the part of it that names a concept, to a let gives it the name the author had, puts a debugger-visible value on it, and turns the if back into a sentence.

Example

Avoid:

if entry.is_file()
    && !entry.is_hidden()
    && entry.len() > 0
    && entry.depth() < max_depth
    && !ignored.contains(entry.path())
{
    copy(entry);
}

Prefer: a leading part, which a let runs exactly when the if would have

let is_visible_file =
    entry.is_file() && !entry.is_hidden() && entry.len() > 0;
if is_visible_file
    && entry.depth() < max_depth
    && !ignored.contains(entry.path())
{
    copy(entry);
}

Avoid: a part that follows a clause and reads a binding from the chain

if let Some(entry) = next_entry()
    && entry.depth() < max_depth
    && entry.is_file()
    && !entry.is_hidden()
    && entry.len() > 0
    && !ignored.contains(entry.path())
{
    copy(entry);
}

Prefer: a closure, which stays unevaluated until the condition reaches it

let is_visible_file =
    |entry: &Entry| entry.is_file() && !entry.is_hidden() && entry.len() > 0;
if let Some(entry) = next_entry()
    && entry.depth() < max_depth
    && is_visible_file(&entry)
    && !ignored.contains(entry.path())
{
    copy(entry);
}

Source: src/rules/overly_complex_condition.rs

perfectionist::overly_long_file↑ top

activesource file has more lines of code than the configured maximum

What it does

Counts the lines of code in each source file of the crate — the crate root and every mod name; that lives in a file of its own — and flags a file with more than max_lines (default 500).

A line counts when it holds anything other than whitespace and comments, so blank lines, comment-only lines, doc comments, and the lines a block comment spans are free. An inline mod name { ... } is part of the file that holds it, not a file of its own.

A file of test code — a mod tests; behind #[cfg(test)], or any file of an integration-test or benchmark target — is measured like any other; set exempt_tests to leave it alone.

Why restrict this?

This is a stylistic preference, not a correctness issue. A file is the unit a reader opens, searches, and scrolls; when one grows past a few hundred lines it is holding more than one concern, and the reader has to find the boundaries between them that a module split would have drawn. The cap pushes a growing file to become a directory of files named for what each does, and it stops the next addition from landing wherever the file happened to be open.

Example

Avoid: src/config.rs holding the settings struct, the parser for each of three file formats, the environment overlay, and the validation, in 2000 lines.

Prefer: src/config.rs declaring the struct and pub mod env; pub mod json; pub mod toml; pub mod validate; pub mod yaml;, each a file a reader can take in whole.

Source: src/rules/overly_long_file.rs

perfectionist::overly_long_function↑ top

activefunction body has more lines of code than the configured maximum

What it does

Counts the lines of code in a function or method body and flags the body when the count is above max_lines.

A line counts when it holds anything other than whitespace and comments, so blank lines, comment-only lines, doc comments, and the lines a block comment spans are free. The braces that open and close the body are not counted. A function produced by a macro is not measured. A nested function's lines count towards the function that contains it, since they sit in its body.

Test code is measured like any other code; set exempt_tests to leave it alone.

Why restrict this?

This is a stylistic preference, not a correctness issue. A function that runs past a screen is read in pieces, and the reader has to hold the pieces they have scrolled past. A cap on length is the plainest of the size measures, and the one that catches a body that is long without being complex — a sequence of straight-line steps, each of which would read better as a function named for what it does.

Interaction with Clippy

clippy::too_many_lines (pedantic, off by default) measures the same thing, but it measures a function produced by a macro defined in the same crate and skips only what another crate's macro produced, where this rule skips every generated function, whose line count tracks the macro body's layout rather than what a reader scrolls through. Clippy also has no exemption for test code, and its default cap is 100. This rule exists so a project can hold its functions to the same limit it holds their complexity and their local bindings to, with the same knobs. Enable one or the other, not both.

Example

Avoid: a body that reads, validates, transforms, and writes in one run of eighty lines.

Prefer: a body of four calls, each to a function that reads, validates, transforms, or writes.

Source: src/rules/overly_long_function.rs

perfectionist::overly_long_method_chain↑ top

inactiveexpression chain has more method calls than the configured maximum

What it does

Counts the distinct method calls in one expression chain — a.b().c().d() is three — and flags the chain when the count is above max_calls (default 5).

Only method calls on the chain's spine count: the receiver of each call, down to the value the chain starts from. A run of the same method — .arg("-v").arg("build").arg(path) — counts once, so a builder is measured by its distinct calls. A ? or an .await between two calls neither counts nor breaks the chain. A field access (self.items.iter() starts at self.items) and a function call (Vec::new().push(1) starts at Vec::new()) end the spine. A closure's body is measured on its own, so a chain inside a map(|item| ...) is a chain of its own. A chain produced by a macro expansion is not measured.

Test code is measured like any other code; set exempt_tests to leave it alone.

Where a chain stops being readable is a matter of taste, and a codebase written around iterator pipelines will disagree with one written around named intermediates. The rule is therefore inactive by default — enable it per crate by adding to dylint.toml:

[perfectionist]
enable = ["overly_long_method_chain"]

Why restrict this?

This is a stylistic preference, not a correctness issue. A long chain is a pipeline whose intermediate values have no names, so the reader has to infer what each stage produces from the method that consumes it. Up to a handful of stages that is what makes iterator code read well; past that, the reader is holding a stack of anonymous types. Binding a stage to a let named for what it holds, or moving a run of stages into a function named for what it does, gives the reader the name the chain withheld.

Example

Avoid:

let names = manifest
    .dependencies
    .iter()
    .filter(|(_, spec)| spec.is_workspace())
    .map(|(name, _)| name.as_str())
    .filter(|name| !name.starts_with('@'))
    .map(str::to_owned)
    .collect::<Vec<_>>()
    .join(", ");

Prefer:

let workspace_deps = manifest
    .dependencies
    .iter()
    .filter(|(_, spec)| spec.is_workspace())
    .map(|(name, _)| name.as_str());
let unscoped: Vec<String> = workspace_deps
    .filter(|name| !name.starts_with('@'))
    .map(str::to_owned)
    .collect();
let names = unscoped.join(", ");

Source: src/rules/overly_long_method_chain.rs

perfectionist::overly_long_print_macro↑ top

activesplittable print macro with an embedded-newline template exceeds the configured line width

What it does

Flags a println!-style macro call whose format template embeds a \n newline and whose source line is wider than max_line_width display columns, and folds the template across lines with the backslash-newline continuation escape:

println!(
    "error: The error was caused by {err_src}\n\
    hint: Run {magic_cmd} to solve the problem",
);

The rewrite is byte-for-byte output-preserving: every \n stays, and the trailing \<newline><indent> continuation strips exactly the source newline and indentation it adds.

Eligibility is name-based — a curated list of the macros whose output is unchanged by the fold (println!, eprintln!, print!, eprint!, writeln!, write!, and the log family log! / error! / warn! / info! / debug! / trace!), replaced wholesale via target_macros. Macros that return a value (format!, format_args!) or terminate (panic!, assert!, the debug_assert* family, ...) are deliberately out of scope.

A template that is a runtime expression rather than a string literal, a raw string literal, or a template with no foldable interior \n, is left alone.

Why restrict this?

This is a stylistic preference, not a correctness issue. A long single line whose string already contains \n is hard to read and hard to scan in a diff; folding it at the embedded newlines lets each output line read as its own source line without changing a byte of what the program prints.

Example

Avoid:

println!("error: The error was caused by {err_src}\nhint: Run {magic_cmd} to solve the problem");

Prefer:

println!(
    "error: The error was caused by {err_src}\n\
    hint: Run {magic_cmd} to solve the problem",
);

Source: src/rules/overly_long_print_macro.rs

perfectionist::redundant_derive_more_forward_template↑ top

activederive_more formatting template only restates the forward the derive already performs

What it does

Flags a derive_more formatting attribute whose template is nothing but the forward the derive already performs, and suggests deleting it.

A formatting derive on a container with exactly one field forwards to that field, so a template that does nothing but name that field says nothing the derive does not — written inline (#[display("{_0}")], #[display("{the_only_field}")]) or as an argument naming that field (#[display("{}", _0)]), on a struct or on a single-field enum variant. An enum-level #[display("{_variant}")] is the container-level counterpart: it names exactly what each variant would be formatted with anyway.

Each of derive_more's formatting derives is read through its own helper attribute — Display through #[display(...)], LowerHex through #[lower_hex(...)], and so on — but the trait a template forwards to comes from the placeholder, not from the attribute's name. So #[lower_hex("{_0}")] stays unflagged: a bare {} forwards to Display, which is not what the LowerHex derive would have done.

#[debug(...)] is never flagged. derive_more's Debug derive defaults to the struct-shaped Wrapper("inner") output rather than to a forward, so its template always changes the rendering.

A stray positional index warns without an autofix. #[display("{1}", _0)] forwards to the field regardless of the index, so it is redundant — but {1} names an argument that was never supplied, so the fix (delete, or supply the argument) is left to the author.

Beyond that the rule is silent wherever deleting the attribute would change the generated impl — among them an adorned placeholder such as #[display("{_0:>8}")], a variant under any enum-level template, an argument that is not a bare field name (#[display("{}", self.0)]), a bound(...) written beside the template, a cfg-gated container or field, and a template inside a #[cfg_attr(...)].

The rule runs only in a crate where a derive_more derive actually expands. Within one, a derive renamed on import (use derive_more::Display as D;) is not recognised; a re-export under the same name is.

Why restrict this?

This is a stylistic preference, not a correctness issue: the attribute compiles to exactly the code the derive emits without it. It is the same shape of dead weight as an unused import or a needless borrow — it restates what the compiler already does, and a reader has to read the whole template before concluding it changes nothing.

Example

Avoid:

#[derive(derive_more::Display)]
#[display("{_0}")]
struct SanitizedHtml(String);

Prefer:

#[derive(derive_more::Display)]
struct SanitizedHtml(String);

Configuration: none.

Source: src/rules/redundant_derive_more_forward_template.rs

perfectionist::single_letter_closure_param↑ top

activeclosure parameter has a single-letter name

What it does

Flags closure parameters whose identifier is one ASCII letter, unless the closure is a trivial single-expression callback or the identifier is in the conventional-name exempt set (n for an unsigned count, f for a fmt::Formatter, i / j / k for indices). "Single-expression" is a shared precondition for the trivial-callback exception: the body must be a bare expression or a block whose only content is a trailing expression — a body with any let binding or other statement before the trailing expression disqualifies the closure regardless of which branch below would otherwise apply. Given that, one of two further shapes must hold:

• the closure is the immediate argument of a call whose callee name is in the trivial-callback method set (sort_by, sort_by_key, min_by, max_by, binary_search_by, cmp_by, partial_cmp_by, fold, try_fold, ...). The set also covers the matching adaptors from itertools (sorted_by, k_smallest_by, minmax_by_key, ...) and into-sorted (into_sorted_by, into_sorted_by_key, ...);
• the body is a trivial wrapper around the parameter — a field access (|x| x.field), a method call (|x| x.foo()), a one-argument call where the parameter is the sole argument (|x| f(x)), a reference (|x| &x), or a macro call (|x| vec![x], |x| dbg!(x), |x| format!("{x}")). Surrounding * / & operators around the parameter inside any of the non-macro shapes are peeled before the match, so |s| (*s).foo() qualifies.

The conventional-name exempt set matches the one used by perfectionist::single_letter_function_param: |i| ... is the canonical index closure, just as fn step(i: usize) is the canonical index parameter. Bodies that use the index for slicing or arithmetic (|i| &hex[i..i + 2]) are not structurally trivial, so the exempt set is what keeps them out of the diagnostic.

Why restrict this?

This is a stylistic preference, not a correctness issue. A multi-line closure body whose parameter is a single letter forces the reader to scroll back to the closure header for context on every reference. The trivial-callback exception covers sort_by(|a, b| ...) and .map(|x| x.field) shapes that are short enough that the parameter's role is unambiguous from the call site.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character closure parameters, under a single crate-wide threshold and one shared allow-list. It cannot express this rule's trivial-callback exemption (.map(|x| x.field), sort_by(|a, b| ...)) or its conventional-name set, so it flags the short callbacks this rule deliberately allows. Enabling both is redundant — choose the context-aware behaviour here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

.map(|t| {
    let columns = build_columns(t);
    format_row(&columns)
})

Prefer:

.map(|tree_row| {
    let columns = build_columns(tree_row);
    format_row(&columns)
})

Source: src/rules/single_letter_closure_param.rs

perfectionist::single_letter_const_generic↑ top

activeconst generic parameter has a single-letter name

What it does

Flags const generic parameter declarations (<const N: usize>) whose identifier is one ASCII letter.

Why restrict this?

This is a stylistic preference, not a correctness issue. A single-letter const generic parameter is opaque at every use site; a descriptive identifier (LEN, COLS, LANES) documents the parameter's role both at the declaration and at every substitution.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) flags short identifiers in many positions, but explicitly skips const generic parameters — its visitor returns early on GenericParamKind::Const, so it never flags <const N: usize>. This rule covers exactly that gap, so the two are complementary rather than redundant: enable both to also catch short bindings, parameters, and item names.

Example

Avoid:

struct Data<Left, Right, const M: usize, const N: usize> {
    left:  [Left;  M],
    right: [Right; N],
}

Prefer:

struct Data<Left, Right, const LEFT_LEN: usize, const RIGHT_LEN: usize> {
    left:  [Left;  LEFT_LEN],
    right: [Right; RIGHT_LEN],
}

Source: src/rules/single_letter_const_generic.rs

perfectionist::single_letter_const_item↑ top

activeconst item has a single-letter name

What it does

Flags const items (free, associated, and block-level) whose identifier is one ASCII letter.

Why restrict this?

This is a stylistic preference, not a correctness issue. A single-letter const item is opaque at every use site, and the item's scope (module-wide or crate-wide for pub const) makes that opacity propagate. A descriptive identifier (DIMENSION, BUFFER_LEN, MAX_RETRIES) carries its own documentation.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character const item names, under a single crate-wide min-ident-chars-threshold and one shared allow-list that spans several kinds at once — bindings, parameters, and item names. (It skips generic and const-generic parameters, which the single_letter_* family handles separately.) This rule governs const items alone, with its own allowed_idents. Enabling both is redundant for const items — choose per-kind control here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

const N: usize = 2;

Prefer:

const DIMENSION_COUNT: usize = 2;

Source: src/rules/single_letter_const_item.rs

perfectionist::single_letter_function_param↑ top

activefunction parameter has a single-letter name

What it does

Flags function and method parameters whose identifier is one ASCII letter, except for a curated set of conventional names (n for an unsigned count, f for a fmt::Formatter, i / j / k for indices).

Why restrict this?

This is a stylistic preference, not a correctness issue. Parameter names are the first piece of documentation a caller reads (in rustdoc, in IDE hover tips, in error messages). A descriptive parameter name carries that documentation; a single letter does not.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character function parameters, under a single crate-wide min-ident-chars-threshold and one shared allow-list spanning several kinds at once (bindings, parameters, item names). This rule governs parameters alone and ships parameter-tuned default allowances (n, f, i, j, k) plus an independent extra_allowed_idents / extra_denied_idents pair. Enabling both is redundant for parameters — choose per-kind control here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

fn write_row(w: &mut Writer, t: &TreeRow) -> io::Result<()> { ... }

Prefer:

fn write_row(writer: &mut Writer, tree_row: &TreeRow) -> io::Result<()> { ... }

Source: src/rules/single_letter_function_param.rs

perfectionist::single_letter_generic↑ top

activegeneric type parameter has a single-letter name

What it does

Flags generic type parameters whose identifier is one ASCII letter (T, U, K, V, ...).

Why restrict this?

This is a stylistic preference, not a correctness issue. Single-letter generic names propagate through the type signatures and bounds; they force every reader to scroll back to the declaration to recover the role of each parameter. Descriptive names (Element, Key, Reader) keep complex signatures self-documenting.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) flags short identifiers in many positions, but explicitly skips generic type parameters — its visitor returns early on GenericParamKind::Type, so it never flags <T>. This rule covers exactly that gap, so the two are complementary rather than redundant: enable both to also catch short bindings, parameters, and item names.

Single-character lifetime names ('a) are likewise out of scope for the single_letter_* family; clippy::single_char_lifetime_names (restriction) covers those.

Example

Avoid:

pub fn collect_keys<K, V>(map: BTreeMap<K, V>) -> Vec<K> {
    /* fifty lines */
}

Prefer:

pub fn collect_keys<Key, Value>(map: BTreeMap<Key, Value>) -> Vec<Key> {
    /* fifty lines */
}

Configuration: none.

Source: src/rules/single_letter_generic.rs

perfectionist::single_letter_let_binding↑ top

activelet binding has a single-letter name

What it does

Flags let x = ...; bindings whose identifier is one ASCII letter.

Why restrict this?

This is a stylistic preference, not a correctness issue. A descriptive let binding documents what the right-hand side computed; a single-letter name does not. The rule allows let n = ... and other names in a configurable set of exempt identifiers for the well-worn cases (unsigned counts).

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character let bindings, under a single crate-wide min-ident-chars-threshold and one shared allow-list spanning several kinds at once (bindings, parameters, item names). This rule governs let bindings alone, with its own exempt set. Enabling both is redundant for let bindings — choose per-kind control here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

let m = entry.metadata()?;

Prefer:

let metadata = entry.metadata()?;

Source: src/rules/single_letter_let_binding.rs

perfectionist::single_letter_static_item↑ top

activestatic item has a single-letter name

What it does

Flags static items whose identifier is one ASCII letter.

Why restrict this?

This is a stylistic preference, not a correctness issue. A single-letter static item is opaque at every use site, and the item's scope (module-wide or crate-wide for pub static) makes that opacity propagate. A descriptive identifier (BUFFER, CACHE, COUNTER) carries its own documentation.

Interaction with Clippy

clippy::min_ident_chars (restriction, off by default) also flags single-character static item names, under a single crate-wide min-ident-chars-threshold and one shared allow-list that spans several kinds at once — bindings, parameters, and item names. (It skips generic and const-generic parameters, which the single_letter_* family handles separately.) This rule governs static items alone, with its own allowed_idents. Enabling both is redundant for static items — choose per-kind control here, or min_ident_chars for the one-knob sweep.

Example

Avoid:

static N: AtomicUsize = AtomicUsize::new(0);

Prefer:

static REQUEST_COUNT: AtomicUsize = AtomicUsize::new(0);

Source: src/rules/single_letter_static_item.rs

perfectionist::thiserror_usage↑ top

activethiserror import, derive, or attribute; this catalogue prefers derive_more::{Display, Error}

What it does

Flags every use of thiserror in the consumer crate. These syntactic shapes trigger the lint:

1. Derives. #[derive(thiserror::Error)] directly, or #[derive(Error)] / #[derive(te::Error)] when a sibling use thiserror::Error; / use thiserror as te; brings the derive macro into scope under any local name, anywhere in the crate. #[cfg_attr(_, derive(thiserror::Error))] is unwrapped (including nested cfg_attr).
2. Attributes. #[error(...)] attributes attached to an item the rule has already classified as thiserror-derived, on the item, its enum variants, or its fields. #[cfg_attr(_, error(...))] is unwrapped symmetrically with the derive side.
3. Imports. Every use or extern crate statement that brings a thiserror path into scope: use thiserror::*, use thiserror::Error, use thiserror::Error as MyError;, use thiserror::{self as te};, use thiserror as te;, extern crate thiserror;, extern crate thiserror as te;, the braced top-level form use {thiserror::Error, ...};, and pub use re-exports.

The lint is detection-only: it emits a help-style diagnostic pointing at the offending site and suggests migrating to #[derive(derive_more::Display, derive_more::Error)]. There is no autofix — the migration involves a mix of derive-list edits, format-string positional translation (thiserror's {0} ↔ derive_more's {_0}), attribute renames (#[error(...)] ↔ #[display(...)]), and edge cases (#[error(transparent)], #[backtrace]) whose mechanical rewrite is too risky to apply without review.

Alias collection is crate-wide rather than per-module: a use thiserror::Error; anywhere in the crate makes the bare #[derive(Error)] short-hand resolve as thiserror everywhere. In practice that overlap is rare and the rule treats it as acceptable false-positive surface; a project that hits it can suppress individual sites with #[expect(perfectionist::thiserror_usage)].

Why restrict this?

This is a stylistic preference, not a correctness issue. The catalogue picks derive_more for error formatting and source chaining. Mixing in thiserror fragments the attribute vocabulary across the codebase and adds a second derive crate that has no functional capability derive_more lacks. A project that wants the choice the other way around can disable this rule.

Example

Avoid:

use thiserror::Error;

#[derive(Debug, Error)]
pub enum MyError {
    #[error("missing field {0}")]
    MissingField(MissingFieldError),
}

Prefer:

use derive_more::{Display, Error};

#[derive(Debug, Display, Error)]
pub enum MyError {
    #[display("missing field {_0}")]
    MissingField(MissingFieldError),
}

Configuration: none.

Source: src/rules/thiserror_usage.rs

perfectionist::too_many_local_bindings↑ top

activefunction body binds more distinct local names than the configured maximum

What it does

Counts the distinct names a function or method body binds — through let, if let, while let, let ... else, for, match arms, and the parameters of closures it contains — and flags the body when the count is above max_bindings.

A name counts once however many times it is bound, so shadowing (let input = input.trim();) is free. A name that begins with _ is not counted, nor is a name invented by a macro expansion or by a compiler desugaring, nor are the function's own parameters. A name the author passed into a macro does count, even though the let around it came from the expansion. A nested function is counted on its own, not as part of the function that contains it. A function that is itself produced by a macro is not counted.

Test code is counted like any other code; set exempt_tests to leave it alone.

Why restrict this?

This is a stylistic preference, not a correctness issue. Every local name is a value the reader has to keep track of, and a body that needs many of them at once is usually several steps written out in sequence, each with its own intermediates. Unlike a branch or a loop, such a body has no control flow for a complexity measure to see, so it passes those checks however long it grows. The cap pushes each step into a function of its own, whose signature then names the few values that cross between them, or pushes related intermediates into a struct.

Interaction with Clippy

clippy::too_many_arguments caps the names that enter a function through its signature; this rule caps the ones the body introduces. clippy::too_many_lines caps the body's length instead, which a wrapped chain or a long literal can exhaust without introducing a single name.

Example

Avoid: one body that reads, parses, validates, and reports

fn load(path: &Path) -> Result<Config, Error> {
    let raw = fs::read_to_string(path)?;
    let document = toml::from_str::<Document>(&raw)?;
    let registry = document.registry.unwrap_or_default();
    let registry_url = Url::parse(&registry)?;
    let store_dir = document.store_dir.map(PathBuf::from);
    let store_dir_exists = store_dir.as_deref().is_some_and(Path::exists);
    let concurrency = document.concurrency.unwrap_or(16);
    let concurrency_clamped = concurrency.clamp(1, 64);
    // ... eight more
    Ok(Config { registry_url, store_dir, concurrency: concurrency_clamped, .. })
}

Prefer: one function per step

fn load(path: &Path) -> Result<Config, Error> {
    let document = read_document(path)?;
    Ok(Config {
        registry_url: parse_registry(&document)?,
        store_dir: resolve_store_dir(&document),
        concurrency: clamp_concurrency(&document),
    })
}