# Code Quality Standards
## 🚨 SENIOR DEVELOPER GUIDELINES 🚨
**CRITICAL: This project follows SIMPLE, MAINTAINABLE patterns. DO NOT over-engineer!**
### Code Philosophy
1. **SIMPLE over CLEVER**: Write obvious code that any developer can understand
2. **EXPLICIT over IMPLICIT**: Prefer clear, direct implementations over abstractions
3. **FLAT over NESTED**: Avoid deep inheritance, complex factories, or excessive abstraction layers
4. **FOCUSED over GENERIC**: Write code for the specific use case, not hypothetical future needs
### Forbidden Patterns (DO NOT ADD THESE)
❌ **Abstract base classes** or complex inheritance hierarchies
❌ **Factory patterns** or dependency injection containers
❌ **Decorators for cross-cutting concerns** (logging, caching, performance monitoring)
❌ **Complex configuration classes** with nested structures
❌ **Async/await patterns** unless absolutely necessary
❌ **Connection pooling** or caching layers
❌ **Generic "framework" code** or reusable utilities
❌ **Complex error handling systems** or custom exceptions
❌ **Performance optimization** patterns (premature optimization)
❌ **Enterprise patterns** like singleton, observer, strategy, etc.
### Required Patterns (ALWAYS USE THESE)
✅ **Direct function calls** - no indirection or abstraction layers
✅ **Simple classes** with clear, single responsibilities
✅ **Environment variables** for configuration (no complex config objects)
✅ **Explicit imports** - import exactly what you need
✅ **Basic error handling** with try/catch and simple return dictionaries
✅ **Straightforward control flow** - avoid complex conditional logic
✅ **Standard library first** - only add dependencies when absolutely necessary
### Implementation Rules
1. **One concept per file**: Each module should have a single, clear purpose
2. **Functions over classes**: Prefer functions unless you need state management
3. **Direct SDK calls**: Call Databricks SDK directly, no wrapper layers
4. **Simple data structures**: Use dicts and lists, avoid custom data classes
5. **Basic testing**: Simple unit tests with basic mocking, no complex test frameworks
6. **Minimal dependencies**: Only add new dependencies if critically needed
### Code Review Questions
Before adding any code, ask yourself:
- "Is this the simplest way to solve this problem?"
- "Would a new developer understand this immediately?"
- "Am I adding abstraction for a real need or hypothetical flexibility?"
- "Can I solve this with standard library or existing dependencies?"
- "Does this follow the existing patterns in the codebase?"
## Python Code Quality
### Linting and Formatting
- **Linter**: ruff for fast Python linting and formatting
- **Configuration**: See [pyproject.toml](mdc:pyproject.toml) for ruff settings
- **Line Length**: Maximum 80 characters (CLAUDE.md standard)
- **Indentation**: Use tabs for indentation (CLAUDE.md standard)
- **Quotes**: Single quotes for strings (except to avoid escaping)
### Code Style Rules
```python
# ✅ GOOD: Simple, direct implementation
def get_workspace_client() -> WorkspaceClient:
host = os.getenv('DATABRICKS_HOST')
token = os.getenv('DATABRICKS_TOKEN')
return WorkspaceClient(host=host, token=token)
# ❌ BAD: Over-engineered with abstractions
class AbstractDatabricksClientFactory(ABC):
@abstractmethod
def create_client(self) -> WorkspaceClient: ...
class ConfigurableDatabricksClientFactory(AbstractDatabricksClientFactory):
def __init__(self, config: DatabricksConfig): ...
```
### Type Hints
- **Required**: Use type hints for all function parameters and return values
- **Simple types**: Use basic types (str, int, dict, list) over complex generics
- **Avoid**: Complex type hierarchies or custom type systems
- **Import**: `from typing import Optional, Union, Any` only when necessary
### Documentation
- **Docstrings**: Use simple, clear descriptions
- **Function Docs**: Document what the function does, not how it works
- **Class Docs**: Document class purpose only
- **Module Docs**: Document module purpose and exports
### Tool System Architecture
The modular tools system (`server/tools/`) is organized into specialized modules:
- `core.py` - Health checks and basic operations
- `sql_operations.py` - SQL warehouse and query tools
- `unity_catalog.py` - Unity Catalog operations (catalogs, schemas, tables)
- `jobs_pipelines.py` - Job and DLT pipeline management
- `workspace_files.py` - Workspace file operations
- `dashboards.py` - **Comprehensive dashboard management tools** (only Lakeview)
- `repositories.py` - Git repository integration
- `data_management.py` - DBFS and data operations (commented out)
- `governance.py` - Governance tools (commented out)
### Adding New Tools
Tools are automatically registered when added to modules. Follow existing patterns:
```python
def load_module_tools(mcp_server):
"""Register tools from this module."""
@mcp_server.tool
def your_new_tool(param: str) -> dict:
"""Tool description for Claude."""
# Implementation using Databricks SDK
return {"result": "data"}
```
**Key principles:**
- Direct Databricks SDK calls (no wrappers)
- Simple error handling with try/catch
- Return dictionaries with consistent structure
- No decorators, no abstractions, no magic
## TypeScript Code Quality
### Linting and Formatting
- **Linter**: ESLint with TypeScript support
- **Formatter**: Prettier for consistent code formatting
- **Configuration**: See [client/package.json](mdc:client/package.json) for scripts
### Code Style Rules
```tsx
// ✅ GOOD: Simple, focused component
interface UserProfile {
id: string
name: string
email: string
}
const handleUserUpdate = (user: UserProfile): void => {
// Direct implementation
}
// ❌ BAD: Over-engineered with unnecessary abstractions
interface AbstractUserProfile<T extends string> {
id: T
name: string
email: string
}
class UserProfileManager<T extends string> {
private profile: AbstractUserProfile<T>
// Complex implementation
}
```
### TypeScript Best Practices
- **Strict Mode**: Enable all strict TypeScript options
- **Interface over Type**: Prefer interfaces for object shapes
- **Utility Types**: Use Partial, Pick, Omit sparingly
- **Generic Types**: Use generics only when absolutely necessary
## General Code Quality
### Naming Conventions
- **Python**: snake_case for functions and variables, PascalCase for classes
- **TypeScript**: camelCase for variables and functions, PascalCase for components
- **Constants**: UPPERCASE for constants
- **Files**: kebab-case for file names
### Code Organization
- **Imports**: Group imports (standard library, third-party, local)
- **Functions**: Keep functions focused and single-purpose
- **Classes**: Use simple classes with clear responsibilities
- **Modules**: Organize related functionality into modules
### Error Handling
- **Python**: Use try-catch blocks with simple error handling
- **TypeScript**: Use proper error boundaries and error types
- **Logging**: Log errors with appropriate log levels
- **User Experience**: Provide meaningful error messages
### Examples of Good vs Bad Code
**❌ BAD (Over-engineered):**
```python
class AbstractDatabricksClientFactory(ABC):
@abstractmethod
def create_client(self) -> WorkspaceClient: ...
class ConfigurableDatabricksClientFactory(AbstractDatabricksClientFactory):
def __init__(self, config: DatabricksConfig): ...
```
**✅ GOOD (Simple):**
```python
def get_workspace_client() -> WorkspaceClient:
host = os.getenv('DATABRICKS_HOST')
token = os.getenv('DATABRICKS_TOKEN')
return WorkspaceClient(host=host, token=token)
```
**❌ BAD (Complex configuration):**
```python
class DatabaseConfig(BaseModel):
host: str = Field(..., description="Database host")
class AppConfig(BaseSettings):
database: DatabaseConfig
security: SecurityConfig
monitoring: MonitoringConfig
```
**✅ GOOD (Direct environment variables):**
```python
class Config:
def __init__(self):
self.host = os.getenv('DATABRICKS_HOST')
self.token = os.getenv('DATABRICKS_TOKEN')
```
## Summary: What Makes This Project "Senior Developer Approved"
✅ **Readable**: Any developer can understand the code immediately
✅ **Maintainable**: Simple patterns that are easy to modify
✅ **Focused**: Each module has a single, clear responsibility
✅ **Direct**: No unnecessary abstractions or indirection
✅ **Practical**: Solves the specific problem without over-engineering
When in doubt, choose the **simpler** solution. Your future self (and your teammates) will thank you.
description: Code quality standards emphasizing simple, maintainable patterns over complex abstractions
globs:
alwaysApply: false
---
