The-Somnus-Project/docs/sharded-architecture/coding-standards.md

Coding Standards

This document defines the coding style and conventions for all Python code in the Somnus Project. Adhering to these standards is crucial for maintaining code quality, readability, and consistency.

General Principles

• Clarity over cleverness: Write code that is easy to understand.
• Follow PEP 8: When in doubt, refer to the PEP 8 style guide.

Naming Conventions

• Classes: PascalCase (e.g., PlayerController, GameManager).
• Functions and Methods: snake_case (e.g., move_player, calculate_damage).
• Variables: snake_case (e.g., player_health, move_speed).
• Constants: ALL_CAPS_SNAKE_CASE (e.g., MAX_HEALTH, DEFAULT_SPEED).
• Modules: snake_case (e.g., game_manager, resource_manager).

Code Formatting

• Indentation: Use 4 spaces, not tabs.
• Line Length: Keep lines under 79 characters where possible (PEP 8), though up to 99 is acceptable for readability.
• Blank Lines: Use single blank lines to separate functions and logical blocks of code within functions for readability. Use two blank lines between class definitions.

Scripting Best Practices

• Type Hinting: Use type hints for variables, function arguments, and return values wherever possible. This improves code clarity and helps prevent bugs.

  player_health: int = 100
  
  def take_damage(self, amount: int) -> None:
      self.player_health -= amount
      if self.player_health < 0:
          self.player_health = 0
  

• Docstrings: Use docstrings to document modules, classes, and functions. Follow the Google Python Style Guide for docstrings.
• Comments: Add comments to explain why a piece of code does something, not what it does. The code itself should be clear enough to explain the 'what'.
• Agent Development Support: Agents writing or analyzing code may wish to use the configured ref MCP server for enhanced code understanding and generation capabilities.