ALL-REAC0002 · file_local_public_declaration
Count public declarations only their own file ever uses.
This is a deterministic rule for all languages. Read its implementation.
Definition
Section titled “Definition”Report a public declaration that at least one reference reaches, where every one of those references sits in the file that declares it. A name published to the whole repository but used in exactly one place is stating a contract it does not have. Making it nonpublic tells a reader the truth, and it frees the declaration to change without a repository-wide search.
This is the ordinary way a module accumulates surface. A helper is written public because everything else nearby is public, and nothing ever calls it from outside.
Evidence
Section titled “Evidence”Each finding names the declaration, its kind, and how many references its own file makes against the nothing every other file makes. The repair is a choice, because a name is either an interface nobody adopted yet or a helper that was never meant to be one. The value is the number of such declarations.
Exceptions
Section titled “Exceptions”A class is never counted, because the one repair this rule offers is a nonpublic name and a
leading underscore belongs to functions, methods, and variables rather than to a type. A class
used in one file is named for what it is, and where it is genuinely dead ALL-REAC0001 says
so. A module a test runner collects is skipped, since its declarations are reached by name. A
published API, a framework hook, and a plugin entry point are reached from outside the
repository, so their reference counts understate them. A declaration a test file reaches is
reached from another file and is not counted here.
Examples
Section titled “Examples”A public def parse_header(line) that only its own module calls returns 1 and should become
_parse_header or move inside its single caller. The same function called from two modules
returns 0, and so does a class HeaderPolicy its own module is the only reader of.
References
Section titled “References”- Cites “PEP 8, Style Guide for Python Code”, public and internal interfaces. Open reference
- Cites “A Philosophy of Software Design”, on narrow interfaces
- Cites “Effective Go”, names and exported identifiers. Open reference