Code Organization

Encapsulation

Use wrapper methods instead of exposing internal dependencies. This provides better encapsulation and makes refactoring easier.

Bad example:

class DownloadService:
    def __init__(self):
        self.repository = HuggingFaceRepository()

    def download_model(self, id: str):
        # Directly accessing internal API of repository
        repo_info = self.repository.api.repo_info(id)
        ...

Good example:

class HuggingFaceRepository:
    def get_repo_info(self, id: str) -> RepoInfo:
        """Get repository information from HuggingFace Hub."""
        return self.api.repo_info(id)

class DownloadService:
    def __init__(self):
        self.repository = HuggingFaceRepository()

    def download_model(self, id: str):
        # Using wrapper method - better encapsulation
        repo_info = self.repository.get_repo_info(id)
        ...

Benefits:

• Hides implementation details
• Makes it easier to add logging, caching, or error handling
• Simplifies testing (mock the wrapper instead of internal dependencies)
• Allows changing the underlying implementation without affecting callers

File Modularity

Never put everything in one file. Split large files into focused modules with single responsibilities.

When to split:

• File exceeds 150 lines
• Class has more than 5 distinct responsibilities
• Logic can be grouped into clear, reusable modules

How to split:

• Group related functions into separate files
• Create modules by responsibility (e.g., repository.py, filters.py, file_downloader.py)
• Keep main service file as a thin orchestration layer
• Use clear, descriptive filenames that indicate purpose

Example structure:

features/downloads/
  ├── services.py          # Main orchestration only
  ├── repository.py        # Repository operations
  ├── file_downloader.py   # Low-level file operations
  └── filters.py           # Filtering logic

Function Design

One function, one responsibility. Each function should do exactly one thing and do it well.

Bad example:

def process_user(user_data):
    # Validates, saves, and sends email - too many responsibilities
    if not user_data.get('email'):
        raise ValueError('Email required')
    db.save(user_data)
    send_welcome_email(user_data['email'])
    return user_data

Good example:

def validate_user_data(user_data):
    if not user_data.get('email'):
        raise ValueError('Email required')

def save_user(user_data):
    return db.save(user_data)

def send_welcome_email(email):
    # Only handles email sending
    ...

Code Clarity

Use descriptive variable names in loops. Never use single letters that don't convey meaning.

Bad examples:

for p in components_scopes:  # What is 'p'?
for i in users:              # 'i' suggests index, but it's a user
for x in files:              # Meaningless

Good examples:

for component_scope in components_scopes:
for scope in components_scopes:  # If 'scope' is clear in context
for user in users:
for file_path in files:

Minimize comments—write self-documenting code instead.

• Only add comments for non-obvious business logic or workarounds
• Never comment on what the code does (code should be clear enough)
• Only comment on why it does it (when it's not obvious)
• Add comments for hacky solutions that can't be avoided

Bad examples:

# Increment counter
counter += 1

# Loop through users
for user in users:
    # Process user
    process_user(user)

Good examples:

# Workaround for HuggingFace API returning inconsistent revision formats
# See: https://github.com/huggingface/huggingface_hub/issues/1234
revision = getattr(repo_info, 'sha', None) or 'main'

# Skip lock acquisition here because this method is always called
# within a context that already holds the lock
self._update_state_unsafe(new_state)

Using Unique Identifiers

Use database IDs or unique identifiers for adapter/instance names. When working with multiple instances of objects (adapters, plugins, etc.), use database IDs or UUIDs for guaranteed uniqueness.

Bad example:

for idx, config in enumerate(lora_configs):
    adapter_name = f"lora_{idx}"  # Index can change if list order changes
    self.pipe.load_lora_weights(config.file_path, adapter_name=adapter_name)

Good example:

for config in lora_configs:
    adapter_name = f"lora_{config.id}"  # Database ID is stable and unique
    self.pipe.load_lora_weights(config.file_path, adapter_name=adapter_name)

Benefits:

• Guaranteed uniqueness
• Stable across reorderings
• Easier to debug (can trace back to database)
• More predictable behavior