8910413315
Concerns (6 files): - coding-style.md (163 lines): patterns, anti-patterns, error handling, SOLID - naming.md (105 lines): naming conventions table per language - documentation.md (149 lines): docstrings, WHY vs WHAT, README standards - testing.md (134 lines): AAA pattern, mocking philosophy, TDD - git-workflow.md (118 lines): conventional commits, branch naming, PR format - project-structure.md (82 lines): directory layout, entry points, config placement Languages (4 files): - python.md (224 lines): uv, ruff, pyright, pytest, pydantic, idioms, anti-patterns - typescript.md (150 lines): strict mode, discriminated unions, satisfies, as const - nix.md (129 lines): flake structure, module patterns, alejandra, anti-patterns - shell.md (100 lines): set -euo pipefail, shellcheck, quoting, POSIX Frameworks (1 file): - n8n.md (42 lines): workflow design, node patterns, Error Trigger, security Context budget: 975 lines (concerns + python) < 1500 limit Refs: T6-T16 of rules-system plan
3.3 KiB
Documentation Rules
When to Document
Document public APIs. Every public function, class, method, and module needs documentation. Users need to know how to use your code.
Document complex logic. Algorithms, state machines, and non-obvious implementations need explanations. Future readers will thank you.
Document business rules. Encode domain knowledge directly in comments. Don't make anyone reverse-engineer requirements from code.
Document trade-offs. When you choose between alternatives, explain why. Help future maintainers understand the decision context.
Do NOT document obvious code. Comments like // get user add noise. Delete them.
Docstring Formats
Python (Google Style)
def calculate_price(quantity: int, unit_price: float, discount: float = 0.0) -> float:
"""Calculate total price after discount.
Args:
quantity: Number of items ordered.
unit_price: Price per item in USD.
discount: Decimal discount rate (0.0 to 1.0).
Returns:
Final price in USD.
Raises:
ValueError: If quantity is negative.
"""
JavaScript/TypeScript (JSDoc)
/**
* Validates user input against security rules.
* @param {string} input - Raw user input from form.
* @param {Object} rules - Validation constraints.
* @param {number} rules.maxLength - Maximum allowed length.
* @returns {boolean} True if input passes all rules.
* @throws {ValidationError} If input violates security constraints.
*/
function validateInput(input, rules) {
Bash
#!/usr/bin/env bash
# Deploy application to production environment.
#
# Usage: ./deploy.sh [environment]
#
# Args:
# environment: Target environment (staging|production). Default: staging.
#
# Exits:
# 0 on success, 1 on deployment failure.
Inline Comments: WHY Not WHAT
Incorrect:
# Iterate through all users
for user in users:
# Check if user is active
if user.active:
# Increment counter
count += 1
Correct:
# Count only active users to calculate monthly revenue
for user in users:
if user.active:
count += 1
Incorrect:
// Set timeout to 5000
setTimeout(() => {
// Show error message
alert('Error');
}, 5000);
Correct:
// 5000ms delay prevents duplicate alerts during rapid retries
setTimeout(() => {
alert('Error');
}, 5000);
Incorrect:
# Remove temporary files
rm -rf /tmp/app/*
Correct:
# Clear temp directory before batch import to prevent partial state
rm -rf /tmp/app/*
Rule: Describe the intent and context. Never describe what the code obviously does.
README Standards
Every project needs a README at the top level.
Required sections:
- What it does - One sentence summary
- Installation - Setup commands
- Usage - Basic example
- Configuration - Environment variables and settings
- Contributing - How to contribute
Example structure:
# Project Name
One-line description of what this project does.
## Installation
```bash
npm install
Usage
npm start
Configuration
Create .env file:
API_KEY=your_key_here
Contributing
See CONTRIBUTING.md.
**Keep READMEs focused**. Link to separate docs for complex topics. Don't make the README a tutorial.