Use clear names

Rule: choose concise, semantically accurate, and responsibility-respecting names for identifiers (variables, functions, classes, modules). Motivation: clear names reduce cognitive load, avoid ambiguity, and prevent leaking responsibilities across layers.

Guidelines:

• Prefer concise domain nouns; drop redundant suffixes or qualifiers. Example: use tagger (not tagger_plugin), directory name taggers (not taggers_plugin). For classes, avoid duplicative internal fields like _categorical when the class name already communicates the type.
  • Bad: tagger_plugin: str
  • Good: tagger: str
• Make names reflect their return type/semantics. Use verbs for actions and nouns for data; name boolean flags clearly. Examples:
  • get_trials_completed() -> count_completed_trials() # returns int
  • get_* should return objects or collections; count_/is_/has_ for predicates or numeric counts.
• For binary options prefer a boolean with a neutral name rather than a Literal with two labels. Example:
  • mode: Literal[“remove_inhibitions”,”increase_inhibitions”] -> reverse: bool = False
• Express units and domains in names. If a value is a fraction (0..1), name it accordingly. Example:
  • winsorization_level (0..100) -> winsorization_quantile (0.0..1.0)
• Do not embed UI/label or management concerns inside low-level classes. E.g., avoid passing instance_name or display labels into classes that represent logic; labeling/aggregation belongs to higher-level code.
  • Bad: Scorer(…, instance_name=…)
  • Good: keep Scorer focused on behavior; management code assigns names/labels.
• Flatten and standardize config types for plugins. Prefer a nested Settings model named Settings or a top-level Settings type over nonstandard nested names like PluginSettings. This keeps plugin initialization consistent.
  • Bad: class KLDivergence(Scorer): class PluginSettings(BaseModel): …
  • Good: class KLDivergence(Scorer): class Settings(BaseModel): … or unnest to module-level Settings.
• Keep internal naming consistent; map to user-facing labels only at presentation boundaries. If internal code uses scores, stick with scores; render them as “Metrics” only in displays.

Code examples:

• Rename and semantics:
  • Before: study_name = “heretic_study_” + “_“.join(study_components)
  • After: study_name = “_“.join(study_components) # omit unnecessary prefix
• Function naming:
  • Before: def get_trials_completed() -> int: …
  • After: def count_completed_trials() -> int: …

Application checklist for reviewers:

1. Ask: Is any word redundant given the type or context? Remove it. (e.g., _plugin, _categorical)
2. Ask: Does the name indicate the value’s type/unit/semantics? If not, clarify (e.g., quantile, is, count_).
3. Ask: Is responsibility leaking into this identifier? Move UI/label/instance concerns out of logical classes.
4. Verify consistency across modules (e.g., scores vs metrics) and pick a single internal term.

References: discussion indices [0,1,3,4,6,7,8,10,11,12,13].