<!--
title: Favor clarity over brevity
domain: data-systems
topic: Code Style
language: Python
source: pola-rs/polars
updated: 2025-03-11
url: https://awesomereviewers.com/reviewers/polars-favor-clarity-over-brevity/
-->

Always prioritize code readability and maintainability over concise but cryptic implementations. Extract repeated logic into well-named helper functions, use keyword-only arguments for clearer APIs, and structure complex string operations for better readability.

For repeated code:
```python
# Instead of this:
if engine == "auto" and get_engine_affinity() != "auto":
    engine = get_engine_affinity()

# Extract into a reusable function:
def _select_engine(engine: EngineType) -> EngineType:
    return get_engine_affinity() if engine == "auto" else engine

# Then use it:
engine = _select_engine(engine)
```

For clearer APIs, use keyword-only arguments:
```python
# Instead of this:
def from_buffer(self, dtype: PolarsDataType, endianness: Endianness = "little"):
    ...

# Prefer this:
def from_buffer(self, *, dtype: PolarsDataType, endianness: Endianness = "little"):
    ...
```

For complex string operations, prefer readable structures:
```python
# Instead of complex concatenation:
categories = (
    [",".join(f"{cat!r}" for cat in categories[:3])]
    + ["…"]
    + [",".join(f"{cat!r}" for cat in categories[-3:])]
)

# Use more readable structure:
categories = [
    ",".join(repr(cat) for cat in categories[:3]),
    "…",
    ",".join(repr(cat) for cat in categories[-3:]),
]
```