Python Style Guide and Development Conventions

PYTHON_STYLE_GUIDE.md

Code Style Guide and Development Conventions

General Style Philosophy

• NEVER ADD COMPLEXITY until you are 100% sure it is required. No "just in case" wrappers, separators, fallbacks, extra regex passes, defensive checks, helper functions, or speculative state. Run the actual code, observe the exact failure, then fix the specific cause. Adding constructs that "might help" hides the real problem and creates compounding feedback loops where downstream code compensates for upstream additions.
• Less is more: prefer concise code, only add complexity when strictly necessary.
• Encapsulate related data and behavior into classes, hiding internal details.
• Abstract common patterns into reusable functions and classes.
• Write self-documenting code: meaningful names, minimal comments.
• Eliminate redundant code through refactoring and reuse.
• Never add new classes without a backing architecture design.
• Avoid redundancy among class attributes.

Lean Code Rules

• Inline single-use vars and functions - don't create variables just to pass to functions, don't extract functions used only once
• Remove type hints except for non-obvious return types
• Remove unnecessary and banner comments - no ASCII art separators, code should be self-documenting
• Implicit boolean checks - use if not x unless None is special
• Avoid variable suffixes referring to type (_list, _dict, _str) or implementation details (_cm, _dbm, _ms). Use meaningful names; clarify in side comments if needed
• Remove trailing whitespace
• Hoist conditional mutations if used by both branches
• Extract duplicate expressions into variables
• Name magic strings and values used in more than one place whose content is not self-documenting — a named constant eliminates the need for comments at each usage site
• Minimize line count - comprehensions, ternaries, dict.get()
• Use Python idioms - decorators, context managers, unpacking, walrus operator :=
• Early returns - exit early to avoid deep nesting; no else after return
• Negative conditions first - handle error/edge cases first, happy path flows naturally
• No dead code - remove commented-out code, unused imports, unreachable branches
• Avoid defensive programming internally - trust internal code, validate only at system boundaries
• Prefer stdlib over dependencies
• One statement per line, except tightly related assignments like a, b = b, a
• Keep functions about 1 page long
• Brief docstrings: 2 lines for function use + 1 line per parameter, mention types only when not easily deduced

Code Organization

Principle: Top-down, public before private, high-level before implementation details. Place functions right after where they are used, NEVER before.

Module-level:

1. High-level public constants (after imports)
2. Main/primary class
3. Supporting classes
4. Utility functions
5. Low-level implementation constants (at the bottom)

Within classes:

1. Constructors and factory methods
2. Public methods (top-down by call hierarchy)
3. Non-public methods (_ prefix, top-down)

Utility functions: Place at module bottom. Move to a common module only if reusable AND that module is already imported. Don't create utility modules for one or two functions.

API Design Philosophy

Make the API natural for both humans and AI/LLM interaction:

• Provide generic API calls where it makes sense, with parameters to cover multiple cases
• Allow direct property access where it makes sense
• Avoid unnecessary abstraction layers
• Prefer OO design unless it results in more boilerplate than the task requires
• Avoid Java/J2EE patterns: No *Interface classes or unnecessary abstraction layers
• No duplication: One command = one schema. Don't create multiple schemas for the same command with slightly different parameters - use optional parameters instead

Design Philosophy

• Fix architecturally, not defensively: when a bug or edge case arises, find the design that makes it impossible rather than patching around it. Workarounds accumulate and obscure the real structure.

Error Handling Philosophy

• Fail fast with clear messages: Raise specific errors that guide users to solutions
• Check dependencies at runtime: Validate required dependencies, like InfluxDB for O1 PM, early during configuration parsing or model generation
• Let exceptions propagate: Don't catch exceptions where they cannot be resolved or enriched. Make sure issues propagate all the way to logs and presented nicely to the User.

Licensing

• Never branch configuration on license availability — configuration MUST NOT behave differently depending on available licenses. A missing license should fail simulation startup, not silently degrade or alter behavior
• Avoid heavyweight licensing imports in utility modules — keep license checks in the modules that enforce them, not in shared utilities that everyone imports

Testing Approach

• Write automated tests with ADK.
• No Mock or behavior-snapshot tests — see QA Guide in .claude/docs/QA_GUIDE.md
• Never reimplement modules in notebooks: Import and use the actual module for validation/testing
• No exception handling in notebooks: NEVER add try/except blocks in notebooks unless absolutely required for functionality. Let exceptions propagate naturally for easier debugging

Bug Fixes Require Tests

CRITICAL: When fixing bugs, ALWAYS add automated regression tests:

• One test per bug fix: Each specific fix should have a corresponding test
• Descriptive test names: Reference the ticket and what's being tested (e.g., test_ue_level_target_policy_status for RIC-10655 Fix #1)
• Document the bug: Include comments linking to the ticket and explaining what bug is being prevented
• Example:

  def test_ue_level_target_policy_status():
      """
      Test RIC-10655 Fix #1: Verify that UELevelTarget policy status uses 'NOT_ENFORCED'
      with underscore (not space) when policy is removed.
      """
      # Test implementation...

Code formatting

Python-Specific Rules

• PEP 8 is the baseline standard
• Max line length: 120 characters
• Logging strings: Use "%s" format, NOT f-strings (security/pylint)

Naming Conventions

• Brief descriptive names: Let AI agents help since they know good English
• Reuse names across functions: When a variable is passed around, keep the same name
• Action-oriented: Method names describe what they do, not how
• Lowercase attributes per PEP 8: sim.cm not sim.CM, even for acronyms
• Avoid "advanced": Use specific terms like detailed_rf_model. Exception: Marketed product feature names

Unit Handling

• Clarify units in comments near value creation or in docstrings
• Push conversions to database queries when possible for optimization

Code Style Specifics

• No obscure intrinsics: Avoid uncommon overloads like __call__ or inequality operators
• No redundant operations: Don't call sim.start() before sim.run_for()
• Avoid heavyweight imports for utilities: Move utilities to common modules
• Avoid static class methods: Use module-level functions. Static methods only for factory methods (MyClass.from_dict()). NEVER create a class holding only static methods: that should be a module!

Keeping the repo clean

• Never commit tokens to repository
• New columns in shared tables or InfluxDB require architect consent - These affect the entire system and must be coordinated with the system architect
• Dependency additions require architect approval - Any new dependency (Python packages, Node.js modules, etc.) must be approved by the system architect. Prepare documentation including license, security review, and reason for inclusion.