71 lines
1.9 KiB
Markdown
71 lines
1.9 KiB
Markdown
---
|
||
applyTo: "**"
|
||
---
|
||
|
||
# Project General Coding Standards (Python - PEP 8)
|
||
|
||
## Naming Conventions
|
||
|
||
- Follow PEP 8 naming conventions strictly
|
||
- Use `snake_case` for variables, functions, and methods
|
||
- Use `PascalCase` for class names
|
||
- Use `UPPER_CASE` for constants
|
||
- Prefix internal/private attributes with a single underscore (`_`)
|
||
- Avoid single-letter variable names unless in very small scopes (e.g., loops)
|
||
|
||
---
|
||
|
||
## Code Style & Formatting
|
||
|
||
- Follow PEP 8 guidelines for formatting
|
||
- Use 4 spaces for indentation (never tabs)
|
||
- Limit lines to 79 characters when possible (max 88 if using Black)
|
||
- Add a blank line between logical sections of code
|
||
- Keep imports organized:
|
||
1. Standard library
|
||
2. Third-party packages
|
||
3. Local imports
|
||
- Avoid wildcard imports (`from module import *`)
|
||
- Remove unused imports and variables
|
||
|
||
---
|
||
|
||
## Clean Code Principles
|
||
|
||
- Write small, focused functions that do **one thing only**
|
||
- Prefer functions over long procedural blocks
|
||
- Keep functions under ~30 lines when possible
|
||
- Use descriptive and meaningful names
|
||
- Avoid code duplication (DRY principle)
|
||
- Prefer explicit code over implicit behavior
|
||
- Avoid deeply nested logic (max 2–3 levels)
|
||
- Use early returns to reduce nesting
|
||
- Keep classes focused and cohesive
|
||
- Write code that is easy to read and maintain
|
||
|
||
---
|
||
|
||
## Function Design
|
||
|
||
- Always use functions when logic can be reused or isolated
|
||
- Add type hints to all function signatures
|
||
- Keep functions pure when possible (avoid side effects)
|
||
- Document functions using docstrings (PEP 257 style)
|
||
|
||
Example:
|
||
|
||
```python
|
||
def calculate_average(values: list[float]) -> float:
|
||
"""
|
||
Calculate the average of a list of numbers.
|
||
|
||
Args:
|
||
values: A list of float numbers.
|
||
|
||
Returns:
|
||
The arithmetic mean of the values.
|
||
"""
|
||
if not values:
|
||
raise ValueError("The values list cannot be empty.")
|
||
|
||
return sum(values) / len(values) |