clean-code

Instruction file imported from nbnHackathon25/nbn-python-package-template (.github/instructions/clean-code.instructions.md). Copyright stays with the author.

General Principles

• Code must be simple, direct, and expressive.
• Always prioritize readability and maintainability over brevity.
• Avoid duplication and ensure all code passes tests.
• Each file, class, and function should have one clear purpose.

Naming

• Use intention-revealing, descriptive names.
• Avoid abbreviations and misleading terms.
• Use nouns for classes, verbs for functions, clear terms for variables.
• Maintain consistent naming conventions across files.

Functions

• Functions must be small and do one thing.
• Use clear, descriptive names.
• Prefer ≤ 2 parameters (max 3).
• Avoid side effects.
• Keep a single level of abstraction within each function.
• Functions must either perform an action or return data, never both.

Comments

• Use comments only when code cannot express intent clearly.
• Good comments: legal notes, rationale, TODOs, warnings.
• Bad comments: redundant, outdated, or restating what code already shows.
• Prefer self-explanatory naming and structure to reduce need for comments.

Formatting

• Structure code like well-written prose.
• Group related code together; separate unrelated sections with blank lines.
• Maintain consistent indentation and spacing.
• Limit vertical length of functions and classes for clarity.

Objects & Data Structures

• Encapsulate data — never expose internal structures directly.
• Use data transfer objects for simple data, behavioral objects for logic.
• Avoid if or switch statements on type; use polymorphism.
• Favor composition over inheritance.

Error Handling

• Use exceptions instead of error codes.
• Don’t return or accept null — prefer safe defaults or option types.
• Keep error-handling separate from main logic.
• Always clean up resources after exceptions.

Boundaries

• Wrap external APIs or libraries in adapter layers.
• Isolate third-party dependencies to protect against change.
• Write tests that capture your expectations for external systems.

Testing

Follow the FIRST principles:

• Fast
• Independent
• Repeatable
• Self-validating
• Timely

Tests must be clean, readable, and reflect real behavior. Never skip tests. Treat test code with the same care as production code.

Classes

• Each class should have a single responsibility (SRP).
• Small and focused: one reason to change.
• Hide implementation details behind clear interfaces.
• Minimize dependencies and coupling.

Systems

• Keep systems modular, decoupled, and testable.
• Use dependency injection to manage dependencies.
• Separate construction from usage.
• Design for scalability and clarity.

Emergent Design

A clean system exhibits these traits:

1. Runs all tests.
2. Contains no duplication.
3. Expresses clear intent.
4. Minimizes the number of classes and methods.

Code Smells (Avoid These)

• Long functions or classes.
• Duplicated code.
• Inconsistent naming.
• Magic numbers or strings.
• Overly commented or confusing code.
• Tight coupling and unclear abstractions.
• Large parameter lists.

Clean Coder Mindset

• Treat code as craftsmanship, not output.
• Refactor continually; leave code cleaner than you found it.
• Strive for clarity, simplicity, and correctness.
• Generate code that another engineer can read and understand instantly.